@wirecat/cli-core 0.496.0 → 0.498.0

package/CHANGELOG.md

@@ -5,7 +5,64 @@ 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.497.0 — 31.10.2026
+
+### Added
+
+- **A calendar source can offer its provider's own search, and the shared `search` uses it.** `CalendarSource.search(calendar,
+  { query, limit })` is optional and answers `{ entries, more }` (new type `SearchPage`). With `serverSearch: true` in
+  `CalendarCommandDeps` (a flag, as `freeBusy`, so the source can stay unbuilt until a profile is open), `search` takes
+  `--backend <archive|server|both>`: `archive`, the default, is the stored search as before; `server` asks the provider
+  over each synced calendar and answers `{ query, by: "server", hits, has_more, untrusted }`, earliest first, cancelled
+  events left out, each hit with `provider`, `account`, `calendar`, `external_id`, `title`, `starts_at`, `ends_at`,
+  `all_day`, `status`, `location`, `url` when there is one, and `found_by: ["server"]`; `both` is refused. New reasons:
+  `search.offline`, `search.no-calendars`, `search.server-options`, `search.one-backend`. `fakeCalendarSource({ search:
+  true })` answers it in tests. A CLI that replaced the shared `search` to reach its provider can drop that
+  ([WC-ARCH-6](https://github.com/WireCatLabs/cli-base/blob/main/docs/standards/architecture.md#wc-arch-6--replace-a-use-case-not-a-command)).
+- **Every shared calendar command declares the entity it answers with, with its schema**
+  ([WC-CMD-19](https://github.com/WireCatLabs/cli-base/blob/main/docs/standards/commands.md#wc-cmd-19--declare-the-entity-a-command-answers-with)),
+  so `commands --json` names it, `commands info --json` exports it and `--fields` can project it: `calendar`
+  (`calendars list`, `sync`, `unsync`), `calendar_busy`, `calendar_sync`, `calendar_sync_progress` (`status`), `event`
+  (`events list`, as before), `calendar_event` (`events show`), `calendar_event_write` (every `events` write),
+  `calendar_search_hit` (a stored or a server hit), `calendar_attendee` (`people list`), `calendar_linked_person`
+  (`people link`), `calendar_link_review` and `calendar_link_resolution`. Each describes the item a host prints, keys
+  in snake_case. The shared `event` entity takes the optional `change`, `changed_at`, `was` and `overlaps` that
+  `events list changed:` and `overlapping` add.
+- **`calendars list` takes a query over the `calendar` entity**: `synced:`, `primary:` and `access_role:` narrow the
+  whole list the provider answered, as `[query...]` after the options
+  ([WC-CMD-20](https://github.com/WireCatLabs/cli-base/blob/main/docs/standards/commands.md#wc-cmd-20--give-a-list-one-query-over-its-entitys-fields-as-its-last-argument)).
+  `events list` keeps its words for now.
+- **The shared `config show --json` names the profile's `kind`, `permissions` and `permission_sources` at the top**,
+  as a messenger's own `config show` does, so an agent reads one shape from every CLI.
+
+### Changed — may break callers
+
+- **The shared calendar commands no longer add their own `--json` and `--jsonl`.** They read the host program's global
+  flags, as every other command does ([WC-CMD-14](https://github.com/WireCatLabs/cli-base/blob/main/docs/standards/commands.md#wc-cmd-14--keep-the-shared-global-flags-at-their-meaning)).
+  The per-command copies showed up in `commands --json` and as `json` and `jsonl` inputs of every calendar MCP tool,
+  and an agent that sent `jsonl: true` was refused with "choose --json or --jsonl", because the MCP runner always adds
+  `--json`. A host that mounts `addCalendarCommands` on a program without global `--json`/`--jsonl` must define them.
+- **`people list` takes `[query...]` instead of `[event]`**: one event's attendees are `people list event:42`, and a
+  bare `people list 42` is now refused as a word with no field. Its MCP tool's input is `query` (`"event:42"`), no
+  longer `event` (WC-CMD-20).
+- **`CalendarCommandDeps.embed` returns `{ model, embedded, left }`**, which `embedEvents` already answers, so
+  `calendar_sync` can describe `embeddings`. It was `Promise<unknown>`.
+
+### Fixed
+
+- **`commands <path>` names the CLI's own groups when the path is unknown.** Its example of one path per call was
+  always `commands messages --json` and `commands chats --json`, even in a calendar CLI that has neither; it now names
+  the groups the caller typed, then the CLI's first groups.
+- **A group given no subcommand points a script at its own help.** In machine mode `tg chats` answered "run `tg
+  --help` for the commands"; it now says `tg chats --help`
+  ([WC-CMD-3](https://github.com/WireCatLabs/cli-base/blob/main/docs/standards/commands.md#wc-cmd-3--give-a-group-without-a-leaf-only-its-help-never-a-hidden-default-action)).
+- **A CLI that is not a messenger (`messenger: false`) no longer shows `config show --bot` or `config set|unset
+  --personal|--bot`.** Only a messenger has bots, and with them the file's personal and bot sections; a calendar or
+  notes CLI listed the options in its help, `commands --json` and its MCP tools with nothing behind them. They are
+  hidden there and still accepted, so a script that passes one keeps working.
+- **`config show` with moved folders no longer says a session made without them reads as none.** That was true
+  before cli-base 0.65.5; a moved run now reads the usual keyring entry, and keeps a sign-in it makes in a temporary
+  entry that `session end` removes. The note says so.
 
 ## 0.496.0 — 31.10.2026
 
@@ -38,6 +95,12 @@ shape of this file.
 
 - **`NoteQuery.refs` checks a list of notes against a query, and `NoteHit.at` is the time `date:` read.**
 
+### Added
+
+- **`chatCoverage` and `ChatCoverage` are exported from `@wirecat/cli-core/services`, and `coverageGaps` from
+  `@wirecat/cli-core/cli`.** A CLI can now pass `ports.coverage` to `gatherProjectEvidence` and build `missing` and
+  `next` for chats held in part, as cli-core's own agenda and search do.
+
 ## 0.495.0 — 31.10.2026
 
 ### Changed — may break callers

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

@@ -0,0 +1,277 @@
+import { type QueryRegistry } from "@wirecat/cli-base/query";
+import type { Command } from "commander";
+import * as v from "valibot";
+export declare const calendar: v.StrictObjectSchema<{
+    readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+    readonly external_id: v.StringSchema<undefined>;
+    readonly title: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly timezone: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly access_role: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly primary: v.BooleanSchema<undefined>;
+    readonly synced: v.BooleanSchema<undefined>;
+    readonly seen_at: v.NullableSchema<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>;
+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 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. */
+        readonly calendar: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>, undefined>;
+        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`">]>;
+        }, 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`">]>;
+    }, undefined>, undefined>, undefined>;
+    readonly unknown: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>;
+}, undefined>;
+export declare const calendarSync: v.StrictObjectSchema<{
+    readonly provider: v.StringSchema<undefined>;
+    readonly account_id: v.NumberSchema<undefined>;
+    readonly window: v.StrictObjectSchema<{
+        readonly from: v.NumberSchema<undefined>;
+        readonly to: v.NumberSchema<undefined>;
+    }, undefined>;
+    readonly calendars: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+    readonly synced: v.ArraySchema<v.StrictObjectSchema<{
+        readonly calendar_id: v.NumberSchema<undefined>;
+        readonly external_id: v.StringSchema<undefined>;
+        readonly title: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly round: v.PicklistSchema<["full", "changes"], undefined>;
+        readonly reset: v.BooleanSchema<undefined>;
+        readonly state: v.PicklistSchema<["partial", "complete"], undefined>;
+        readonly saved: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        readonly removed: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        readonly occurrences: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        readonly unseen: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        readonly error: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    }, undefined>, undefined>;
+    readonly not_synced: v.ArraySchema<v.StrictObjectSchema<{
+        readonly calendar_id: v.NumberSchema<undefined>;
+        readonly external_id: v.StringSchema<undefined>;
+        readonly title: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    }, undefined>, undefined>;
+    readonly complete: v.BooleanSchema<undefined>;
+    readonly state: v.PicklistSchema<["partial", "complete"], undefined>;
+    readonly stopped: v.OptionalSchema<v.PicklistSchema<["requests", "deadline", "cancelled"], undefined>, undefined>;
+    readonly progress: v.StrictObjectSchema<{
+        readonly calendars: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        readonly calendars_done: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        readonly requests: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        readonly saved: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        readonly steps: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+    }, undefined>;
+    readonly hint: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    /** What `sync --embed` embedded: `embedEvents`' answer. */
+    readonly embeddings: v.OptionalSchema<v.StrictObjectSchema<{
+        readonly model: v.StringSchema<undefined>;
+        readonly embedded: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        readonly left: v.BooleanSchema<undefined>;
+    }, undefined>, undefined>;
+}, undefined>;
+export declare const calendarSyncProgress: v.StrictObjectSchema<{
+    readonly calendar_id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+    readonly external_id: v.StringSchema<undefined>;
+    readonly title: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly round: v.NullableSchema<v.PicklistSchema<["full", "changes"], undefined>, undefined>;
+    readonly job: v.StringSchema<undefined>;
+    readonly profile: v.StringSchema<undefined>;
+    readonly done: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+    readonly total: v.NullableSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>, undefined>;
+    readonly remaining: v.NullableSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>, undefined>;
+    readonly state: v.PicklistSchema<["partial", "complete"], undefined>;
+    readonly updated_at: v.NullableSchema<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>;
+    readonly cursor_age_ms: v.NullableSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>, undefined>;
+    readonly line: v.StringSchema<undefined>;
+}, undefined>;
+export declare const calendarEvent: v.StrictObjectSchema<{
+    readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+    readonly event_series_id: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly title: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly description: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly location: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly starts_at: v.NullableSchema<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>;
+    readonly ends_at: v.NullableSchema<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>;
+    readonly timezone: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly origin: v.PicklistSchema<["auto", "owner", "calendar"], undefined>;
+    readonly status: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly all_day: v.BooleanSchema<undefined>;
+    readonly source_deleted_at: v.NullableSchema<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>;
+    readonly deleted_at: v.NullableSchema<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>;
+    readonly created_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 updated_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 change: v.OptionalSchema<v.PicklistSchema<["new", "moved", "cancelled"], undefined>, undefined>;
+    readonly changed_at: v.OptionalSchema<v.NullableSchema<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 was: v.OptionalSchema<v.StrictObjectSchema<{
+        readonly starts_at: v.NullableSchema<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>;
+        readonly ends_at: v.NullableSchema<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 overlaps: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>;
+    readonly ref: v.StringSchema<undefined>;
+    readonly entries: v.ArraySchema<v.StrictObjectSchema<{
+        readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+        readonly calendar_id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+        readonly external_id: v.StringSchema<undefined>;
+        readonly kind: v.StringSchema<undefined>;
+        readonly title: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly status: v.StringSchema<undefined>;
+        readonly event_type: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly own_response: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly starts_at: v.NullableSchema<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>;
+        readonly ends_at: v.NullableSchema<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>;
+        readonly join_url: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly url: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly deleted_at: v.NullableSchema<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 attendees: v.ArraySchema<v.StrictObjectSchema<{
+        email: v.StringSchema<undefined>;
+        name: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        response: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        organizer: v.BooleanSchema<undefined>;
+        optional: v.BooleanSchema<undefined>;
+        resource: v.BooleanSchema<undefined>;
+        self: v.BooleanSchema<undefined>;
+        /** `person:<id>` when the shared store knows the address. */
+        person: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    }, undefined>, undefined>;
+    readonly attachments: v.ArraySchema<v.StrictObjectSchema<{
+        readonly file_id: v.StringSchema<undefined>;
+        readonly title: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly document: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    }, undefined>, undefined>;
+    readonly history: v.ArraySchema<v.StrictObjectSchema<{
+        readonly title: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly starts_at: v.NullableSchema<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>;
+        readonly ends_at: v.NullableSchema<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>;
+        readonly location: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly status: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly changed_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 untrusted: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>;
+}, undefined>;
+/** A hit of the stored search, or with `--backend server` one the provider's own search found and nothing stored. */
+export declare const calendarSearchHit: v.UnionSchema<[v.StrictObjectSchema<{
+    readonly provider: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly account: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly title: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly starts_at: v.NullableSchema<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>;
+    readonly ends_at: v.NullableSchema<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>;
+    readonly all_day: v.BooleanSchema<undefined>;
+    readonly status: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly location: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly url: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly untrusted: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>;
+    readonly ref: v.StringSchema<undefined>;
+    readonly excerpt: v.StringSchema<undefined>;
+    readonly occurrences: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+    readonly updated_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 found_by: v.ArraySchema<v.PicklistSchema<["words", "meaning"], undefined>, undefined>;
+}, undefined>, v.StrictObjectSchema<{
+    readonly provider: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly account: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly title: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly starts_at: v.NullableSchema<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>;
+    readonly ends_at: v.NullableSchema<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>;
+    readonly all_day: v.BooleanSchema<undefined>;
+    readonly status: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly location: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly url: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly untrusted: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>;
+    readonly calendar: v.StringSchema<undefined>;
+    readonly external_id: v.StringSchema<undefined>;
+    readonly found_by: v.ArraySchema<v.LiteralSchema<"server", undefined>, undefined>;
+}, undefined>], undefined>;
+export declare const calendarEventWrite: v.StrictObjectSchema<{
+    readonly operation_id: v.StringSchema<undefined>;
+    readonly event: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly entry: v.OptionalSchema<v.NullableSchema<v.StrictObjectSchema<{
+        readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+        readonly calendar_id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+        readonly external_id: v.StringSchema<undefined>;
+        readonly kind: v.StringSchema<undefined>;
+        readonly title: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly status: v.StringSchema<undefined>;
+        readonly event_type: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly own_response: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly starts_at: v.NullableSchema<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>;
+        readonly ends_at: v.NullableSchema<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>;
+        readonly join_url: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly url: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly deleted_at: v.NullableSchema<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>, undefined>;
+    /** `this`, `series` or `following`. */
+    readonly scope: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    /** Copies the store marked deleted. */
+    readonly removed: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>, undefined>;
+    /** The series a `--following` change ended before the occurrence. */
+    readonly ended: v.OptionalSchema<v.NullableSchema<v.StrictObjectSchema<{
+        readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+        readonly calendar_id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+        readonly external_id: v.StringSchema<undefined>;
+        readonly kind: v.StringSchema<undefined>;
+        readonly title: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly status: v.StringSchema<undefined>;
+        readonly event_type: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly own_response: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly starts_at: v.NullableSchema<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>;
+        readonly ends_at: v.NullableSchema<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>;
+        readonly join_url: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly url: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly deleted_at: v.NullableSchema<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>, undefined>;
+    readonly converted: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly from_calendar: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>, undefined>;
+    readonly calendar: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>, undefined>;
+    readonly hint: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly untrusted: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>;
+}, undefined>;
+export declare const calendarAttendee: v.StrictObjectSchema<{
+    readonly email: v.StringSchema<undefined>;
+    readonly name: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly response: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly organizer: v.BooleanSchema<undefined>;
+    readonly optional: v.BooleanSchema<undefined>;
+    readonly resource: v.BooleanSchema<undefined>;
+    readonly self: v.BooleanSchema<undefined>;
+    readonly person: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    /** How many of the listed events the person attends; only on the week's list. */
+    readonly events: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>, undefined>;
+    readonly untrusted: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>;
+}, undefined>;
+export declare const calendarLinkedPerson: v.StrictObjectSchema<{
+    readonly person: v.StringSchema<undefined>;
+    readonly name: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly identities: v.ArraySchema<v.StringSchema<undefined>, undefined>;
+}, undefined>;
+export declare const calendarLinkReview: v.StrictObjectSchema<{
+    readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+    readonly entry_id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+    readonly reason: v.StringSchema<undefined>;
+    readonly candidates: v.ArraySchema<v.StrictObjectSchema<{
+        readonly ref: v.StringSchema<undefined>;
+        readonly title: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly starts_at: v.NullableSchema<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 untrusted: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>;
+}, undefined>;
+export declare const calendarLinkResolution: v.StrictObjectSchema<{
+    readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+    readonly status: v.StringSchema<undefined>;
+    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`).
+ */
+export declare const declareCalendarAnswers: (program: Command, commands: readonly Command[]) => void;
+export declare const CALENDAR_ANSWER_PATHS: string[];
+/** The provider answers the whole list, never a page, so the terms narrow every calendar it has. */
+export declare const CALENDARS_QUERY: QueryRegistry;
+export declare const PEOPLE_QUERY: QueryRegistry;

package/dist/calendar/cli/answers.js

@@ -0,0 +1,257 @@
+import { annotate } from "@wirecat/cli-base/commands";
+import { queryFieldsOf } from "@wirecat/cli-base/query";
+import * as v from "valibot";
+import { answerEntity } from "../../cli/answer-entity.js";
+import { count, id, text, time, untrusted } from "../../entities/fields.js";
+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 epochWindow = v.strictObject({ from: v.number(), to: v.number() });
+export const calendar = v.strictObject({
+    id,
+    external_id: text,
+    title: nullableText,
+    timezone: nullableText,
+    access_role: nullableText,
+    primary: v.boolean(),
+    synced: v.boolean(),
+    seen_at: nullableTime,
+});
+const busyRow = v.strictObject({
+    /** One of the account's calendars, by its id; or `person`, by the address asked. */
+    calendar: v.optional(id),
+    person: v.optional(text),
+    id: text,
+    busy: v.array(stretch),
+    error: v.optional(text),
+});
+export const calendarBusy = v.strictObject({
+    start: time,
+    end: time,
+    timezone: text,
+    calendars: v.array(busyRow),
+    slots: v.optional(v.array(stretch)),
+    unknown: v.optional(v.array(text)),
+});
+const syncedCalendar = v.strictObject({
+    calendar_id: v.number(),
+    external_id: text,
+    title: nullableText,
+    round: v.picklist(["full", "changes"]),
+    reset: v.boolean(),
+    state: v.picklist(["partial", "complete"]),
+    saved: count,
+    removed: count,
+    occurrences: count,
+    unseen: count,
+    error: v.optional(text),
+});
+export const calendarSync = v.strictObject({
+    provider: text,
+    account_id: v.number(),
+    window: epochWindow,
+    calendars: count,
+    synced: v.array(syncedCalendar),
+    not_synced: v.array(v.strictObject({ calendar_id: v.number(), external_id: text, title: nullableText })),
+    complete: v.boolean(),
+    state: v.picklist(["partial", "complete"]),
+    stopped: v.optional(v.picklist(["requests", "deadline", "cancelled"])),
+    progress: v.strictObject({
+        calendars: count,
+        calendars_done: count,
+        requests: count,
+        saved: count,
+        steps: count,
+    }),
+    hint: v.optional(text),
+    /** What `sync --embed` embedded: `embedEvents`' answer. */
+    embeddings: v.optional(v.strictObject({ model: text, embedded: count, left: v.boolean() })),
+});
+export const calendarSyncProgress = v.strictObject({
+    calendar_id: id,
+    external_id: text,
+    title: nullableText,
+    round: v.nullable(v.picklist(["full", "changes"])),
+    job: text,
+    profile: text,
+    done: count,
+    total: v.nullable(count),
+    remaining: v.nullable(count),
+    state: v.picklist(["partial", "complete"]),
+    updated_at: nullableTime,
+    cursor_age_ms: v.nullable(count),
+    line: text,
+});
+const entry = v.strictObject({
+    id,
+    calendar_id: id,
+    external_id: text,
+    kind: text,
+    title: nullableText,
+    status: text,
+    event_type: nullableText,
+    own_response: nullableText,
+    starts_at: nullableTime,
+    ends_at: nullableTime,
+    join_url: nullableText,
+    url: nullableText,
+    deleted_at: nullableTime,
+});
+const attendee = {
+    email: text,
+    name: nullableText,
+    response: nullableText,
+    organizer: v.boolean(),
+    optional: v.boolean(),
+    resource: v.boolean(),
+    self: v.boolean(),
+    /** `person:<id>` when the shared store knows the address. */
+    person: nullableText,
+};
+const { untrusted: _eventMarker, ...eventFields } = event.entries;
+export const calendarEvent = v.strictObject({
+    ...eventFields,
+    ref: text,
+    entries: v.array(entry),
+    attendees: v.array(v.strictObject(attendee)),
+    attachments: v.array(v.strictObject({ file_id: text, title: nullableText, document: nullableText })),
+    history: v.array(v.strictObject({
+        title: nullableText,
+        starts_at: nullableTime,
+        ends_at: nullableTime,
+        location: nullableText,
+        status: nullableText,
+        changed_at: time,
+    })),
+    untrusted,
+});
+const hitFields = {
+    provider: nullableText,
+    account: nullableText,
+    title: nullableText,
+    starts_at: nullableTime,
+    ends_at: nullableTime,
+    all_day: v.boolean(),
+    status: nullableText,
+    location: nullableText,
+    url: v.optional(text),
+    untrusted,
+};
+/** A hit of the stored search, or with `--backend server` one the provider's own search found and nothing stored. */
+export const calendarSearchHit = v.union([
+    v.strictObject({
+        ...hitFields,
+        ref: text,
+        excerpt: text,
+        occurrences: count,
+        updated_at: time,
+        found_by: v.array(v.picklist(["words", "meaning"])),
+    }),
+    v.strictObject({
+        ...hitFields,
+        calendar: text,
+        external_id: text,
+        found_by: v.array(v.literal("server")),
+    }),
+]);
+export const calendarEventWrite = v.strictObject({
+    operation_id: text,
+    event: nullableText,
+    entry: v.optional(v.nullable(entry)),
+    /** `this`, `series` or `following`. */
+    scope: v.optional(text),
+    /** Copies the store marked deleted. */
+    removed: v.optional(count),
+    /** The series a `--following` change ended before the occurrence. */
+    ended: v.optional(v.nullable(entry)),
+    converted: v.optional(text),
+    from_calendar: v.optional(id),
+    calendar: v.optional(id),
+    hint: v.optional(text),
+    untrusted,
+});
+export const calendarAttendee = v.strictObject({
+    ...attendee,
+    /** How many of the listed events the person attends; only on the week's list. */
+    events: v.optional(count),
+    untrusted,
+});
+export const calendarLinkedPerson = v.strictObject({ person: text, name: nullableText, identities: v.array(text) });
+export const calendarLinkReview = v.strictObject({
+    id,
+    entry_id: id,
+    reason: text,
+    candidates: v.array(v.strictObject({ ref: text, title: nullableText, starts_at: nullableTime })),
+    untrusted,
+});
+export const calendarLinkResolution = v.strictObject({ id, status: text, chosen: nullableText });
+const ANSWERS = {
+    "calendars list": { name: "calendar", schema: calendar },
+    "calendars sync": { name: "calendar", schema: calendar },
+    "calendars unsync": { name: "calendar", schema: calendar },
+    "calendars busy": { name: "calendar_busy", schema: calendarBusy },
+    sync: { name: "calendar_sync", schema: calendarSync },
+    status: { name: "calendar_sync_progress", schema: calendarSyncProgress },
+    "events list": { name: "event" },
+    "events show": { name: "calendar_event", schema: calendarEvent },
+    "events create": { name: "calendar_event_write", schema: calendarEventWrite },
+    "events update": { name: "calendar_event_write", schema: calendarEventWrite },
+    "events delete": { name: "calendar_event_write", schema: calendarEventWrite },
+    "events move": { name: "calendar_event_write", schema: calendarEventWrite },
+    "events respond": { name: "calendar_event_write", schema: calendarEventWrite },
+    search: { name: "calendar_search_hit", schema: calendarSearchHit },
+    "people list": { name: "calendar_attendee", schema: calendarAttendee },
+    "people link": { name: "calendar_linked_person", schema: calendarLinkedPerson },
+    "links review": { name: "calendar_link_review", schema: calendarLinkReview },
+    "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`).
+ */
+export const declareCalendarAnswers = (program, commands) => {
+    const pathOf = (command) => {
+        const words = [];
+        for (let at = command; at && at !== program; at = at.parent)
+            words.unshift(at.name());
+        return words.join(" ");
+    };
+    for (const command of commands) {
+        const answer = ANSWERS[pathOf(command)];
+        if (!answer)
+            continue;
+        if (answer.schema)
+            answerEntity(command, answer.name, answer.schema);
+        else
+            annotate(command, { output: { entity: answer.name } });
+    }
+};
+export const CALENDAR_ANSWER_PATHS = Object.keys(ANSWERS);
+const wholeValues = (registry) => ({
+    ...registry,
+    fields: registry.fields.map((field) => field.native ? { ...field, operators: field.operators.filter((one) => one === "term" || one === "phrase") } : field),
+});
+/** The provider answers the whole list, never a page, so the terms narrow every calendar it has. */
+export const CALENDARS_QUERY = wholeValues({
+    entity: "calendar",
+    backend: "native",
+    fields: queryFieldsOf(calendar, {
+        native: ["synced", "primary", "access_role"],
+        examples: { synced: "synced:true", primary: "primary:true", access_role: "access_role:owner" },
+    }),
+});
+export const PEOPLE_QUERY = wholeValues({
+    entity: "calendar_attendee",
+    backend: "native",
+    fields: queryFieldsOf(calendarAttendee, {
+        native: ["event"],
+        relations: {
+            event: {
+                type: "kw",
+                example: "event:42",
+                relation: "one event's attendees, by its id; without it, everyone in this week's events",
+            },
+        },
+    }),
+});

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

@@ -20,10 +20,19 @@ export interface CalendarCommandDeps {
      * 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;
     /** For a source with `expands: "local"`. */
     expand?: CalendarExpander;
     /** After `sync --embed`: embeds new events for search by meaning (`embedEvents`), as drive's `sync --embed`. */
-    embed?: (max: number) => Promise<unknown>;
+    embed?: (max: number) => Promise<{
+        model: string;
+        embedded: number;
+        left: boolean;
+    }>;
     write: (value: unknown, format: "json" | "jsonl" | "text") => void;
     now?: () => number;
     /** The zone `today`, `week` and a bare date are read in; the computer's when absent. */