@wirecat/cli-core 0.454.0 → 0.456.0

package/CHANGELOG.md

@@ -7,6 +7,65 @@ shape of this file.
 
 ## Unreleased
 
+## 0.456.0 — 27.10.2026
+
+### Added
+
+- **A calendar store for any provider.** `EventStore.removeEntries(calendarId, externalIds, now)` cancels entries a
+  provider names only by id (CalDAV, Outlook) under the same history rules as a cancelled entry: a past event stays,
+  a future one cancels, a series cancels its occurrences. `EventStore.cursor(calendarId)` and
+  `setCursor(calendarId, value, now)` keep where a calendar's sync stopped, in `sync_cursors` under
+  `calendar:<id>`; `null` forgets it. `ical_uid` is defined as the RFC 5545 UID of the series, and an all-day slot's
+  `originalStartsAt` as midnight UTC of its date.
+- **An occurrence names its series in a column (store version 35).** `calendar_entries.series_external_id` holds an
+  occurrence's series id, so an occurrence stored before its series still finds it; `StoredEntry.seriesExternalId`
+  answers it. The migration fills it from `metadata.recurring_event_id`, which the store no longer writes and
+  `ENTRY_METADATA_KEYS` no longer keeps, and rewrites calendar words already stored in Google's spelling into the
+  neutral one (`outOfOffice` → `out-of-office`, `focusTime` → `focus`, `workingLocation` → `working-location`,
+  `fromGmail` → `from-mail`, `needsAction` → `needs-action`, `freeBusyReader` → `free-busy`). Builds that speak
+  version 34 still open the store.
+- **`@wirecat/cli-core/calendar`: one sync for every calendar provider.** A calendar CLI writes a `CalendarSource`
+  (`calendars`, `changes` by page with a cursor or `{ reset: true }`, and `occurrences` when the provider expands a
+  series on request) and calls `syncCalendars(source, store, { accountId })`: the calendar list, then each synced
+  calendar's changes or its whole window (a year back, three months ahead, a full list once a day), the slots of the
+  series that changed, the marking after a full list, and the cursor saved last, so a failed calendar retries the
+  same changes. The traits `expands`, `cursorHoldsWindow` and `fullListOnly` cover Google, Outlook and ICS/CalDAV.
+  `@wirecat/cli-core/calendar/testing` adds `fakeCalendarSource`, `memoryEventStore`, `calendarSourceContract` for an
+  adapter and `calendarSyncContract` for a store, over all twelve trait combinations. The `EventStore` types are
+  exported from `./calendar` too ([Calendars](docs/dev/CALENDARS.md)).
+- **Shared calendar commands and MCP reads.** `addCalendarCommands(program, deps)` (`./calendar/cli`) mounts
+  `calendars list|sync|unsync`, `sync [--full] [--embed]`, `events list [today|week|from:… to:…] [person:…]
+  [calendar:…]`, `events show`, `search` (the events search, over the profile's account), `people list [<event>]`,
+  `people link`, and `links review|resolve`, all read only towards the provider. `calendarTools` and
+  `callCalendarTool` (`./calendar/mcp`) give the reads as MCP tools; without `account_id` they read every account the
+  host serves and name them, and each answer marks the fields an invitation's sender wrote as `untrusted`.
+- **`linkPeople(store, account, person, other)`** (`./services`) is the people service's link as a function, for a
+  tool with no messenger.
+
+### Changed — may break callers
+
+- **Calendar words are neutral, RFC 5545 where it has a word, lower case with hyphens.** `eventType` takes
+  `default`, `out-of-office`, `focus`, `working-location`, `birthday`, `from-mail`; `ownResponse` and a participant's
+  `response` take `needs-action`, `accepted`, `tentative`, `declined`, `delegated`; `accessRole` takes `owner`,
+  `writer`, `reader`, `free-busy`; `transparency` and `visibility` keep their words, now typed. The new types
+  `EntryEventType`, `ParticipantResponse`, `CalendarAccessRole`, `EntryTransparency` and `EntryVisibility` say so,
+  and an adapter translates its provider's words (Google's `outOfOffice`, `needsAction`, `freeBusyReader` …).
+  `UNSEARCHED_EVENT_TYPES` holds the neutral words.
+- **`CalendarInput.syncByDefault` is required** and decides whether a calendar seen for the first time syncs. The
+  store no longer reads Google's `owner` role for it; an adapter sets it (Google: the owner owns the calendar).
+- **`EventStore` gains `removeEntries`, `cursor` and `setCursor`, and `StoredEntry` gains `seriesExternalId`.** A
+  fake event store adds them.
+
+## 0.455.0 — 27.10.2026
+
+### Added
+
+- **A CLI that is not a messenger reuses the shared permission helpers.** `./cli` exports `terminalAsker(command)`,
+  the guard's question at a terminal, and `refuseUnknownPermissionKeys`, the unknown-key refusal for a command the
+  shared check does not key (`api call`, `mcp`). `guardFor` takes `permissionDefaults` on its settings, so a key
+  the CLI defaults to `ask` asks instead of being allowed; without them it keeps the messenger defaults.
+  `terminalAsker`'s `confirmation_required` now names the key in `details.permission`.
+
 ## 0.454.0 — 27.10.2026
 
 ### Added

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

@@ -0,0 +1,24 @@
+import { type Command } from "commander";
+import type { EventStore } from "../../meetings/index.js";
+import type { AccountKey, MessageStore } from "../../store/store.js";
+import type { CalendarExpander, CalendarSource } from "../source.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. */
+    account: AccountKey;
+    /** The shared store: `search`, `people link` and the person of an attendee read it. */
+    messages?: MessageStore;
+    /** The provider; `sync` and `calendars list` read it. */
+    source?: CalendarSource;
+    /** 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>;
+    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. */
+    timezone?: string;
+}
+export declare const addCalendarCommands: (program: Command, deps: CalendarCommandDeps) => void;

package/dist/calendar/cli/index.js

@@ -0,0 +1,173 @@
+import { CliError } from "@wirecat/cli-base";
+import { annotate, sharedCommand } from "@wirecat/cli-base/commands";
+import { timezoneOf } from "@wirecat/cli-base/query";
+import { InvalidArgumentError } from "commander";
+import { searchEvents } from "../../services/events-search.js";
+import { linkPeople } from "../../services/people.js";
+import { calendarIn, calendarItem, EVENTS_QUERY_HELP, eventAnswer, eventIdOf, eventOf, eventsAnswer, eventsFilter, peopleAnswer, resolveAnswer, reviewsAnswer, } from "../reads.js";
+import { syncCalendars } from "../sync.js";
+const LOCAL_READ = { remote: "none", local: "read" };
+const LOCAL_WRITE = { remote: "none", local: "write" };
+const FETCH = { remote: "read", local: "write" };
+const GROUP = { remote: "none", local: "none" };
+/** How many pieces one `sync --embed` embeds, as drive's. */
+const EMBED_MAX = 600;
+const integer = (text) => {
+    if (!/^[1-9]\d*$/.test(text) || !Number.isSafeInteger(Number(text)))
+        throw new InvalidArgumentError("expected a positive integer");
+    return Number(text);
+};
+const addCalendarCommandsDefinition = (program, deps) => {
+    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");
+    };
+    const messages = (what) => {
+        if (!deps.messages)
+            throw new CliError("configuration_error", `${what} needs the shared store`);
+        return deps.messages;
+    };
+    const personOfEmail = deps.messages
+        ? async (email) => {
+            const person = await messages("a person").people.personOf({ provider: "email", id: email });
+            return person ? `person:${person.uid}` : null;
+        }
+        : undefined;
+    const personId = async (reference) => {
+        const text = reference.replace(/^person:/u, "");
+        if (/^[1-9]\d*$/u.test(text))
+            return Number(text);
+        const person = await messages("person:").people.personOf({ provider: "email", id: text.trim().toLowerCase() });
+        return person ? Number(person.uid) : null;
+    };
+    const example = (command, ...lines) => annotate(command, { examples: lines.map((line) => `${program.name()} personal ${line}`) });
+    const source = () => {
+        if (!deps.source)
+            throw new CliError("configuration_error", "the calendar provider is unavailable");
+        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) => {
+        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);
+    });
+    for (const [name, synced] of [
+        ["sync", true],
+        ["unsync", false],
+    ])
+        output(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) => {
+            const calendar = await calendarIn(deps.store, deps.accountId, reference);
+            await deps.store.setCalendarSynced(calendar.id, synced, now());
+            print(calendarItem({ ...calendar, synced }), command);
+        });
+    output(example(annotate(program.command("sync"), { effects: FETCH, offline: false }).description("bring the synced calendars up to date: what changed since the last sync, or everything with --full"), "sync", "sync --full --embed"))
+        .option("--full", "list every synced calendar's window again instead of reading changes")
+        .option("--embed", "also index new events for meaning search, with a model already downloaded")
+        .action(async (opts, command) => {
+        const report = await syncCalendars(source(), deps.store, {
+            accountId: deps.accountId,
+            now: now(),
+            ...(opts.full ? { full: true } : {}),
+            ...(deps.expand ? { expand: deps.expand } : {}),
+        });
+        if (opts.embed && !deps.embed)
+            throw new CliError("configuration_error", "this tool cannot embed events");
+        const embeddings = opts.embed ? await deps.embed?.(EMBED_MAX) : undefined;
+        print(embeddings === undefined ? report : { ...report, embeddings }, command);
+        if (!report.complete)
+            throw new CliError("provider_error", "some calendars did not sync; run sync again to retry them", {
+                reason: "sync.partial",
+            });
+    });
+    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" } })
+        .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"))
+        .option("--limit <n>", "events at most, 1–1000", integer, 100)
+        .action(async (words, opts, command) => {
+        const filter = await eventsFilter(words, {
+            store: deps.store,
+            accountId: deps.accountId,
+            zone: zone(),
+            now: now(),
+            personOf: personId,
+        });
+        print(await eventsAnswer(deps.store, filter && { ...filter, limit: opts.limit }), command);
+    });
+    output(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) => {
+        print(await eventAnswer(await eventOf(deps.store, deps.accountId, eventIdOf(reference)), personOfEmail), 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"))
+        .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) => {
+        print(await searchEvents(messages("search"), words.join(" "), {
+            accounts: [deps.account],
+            limit: opts.limit,
+            offset: opts.cursor,
+            timezone: zone(),
+            command: program.name(),
+            ...(opts.exact ? { exact: true } : {}),
+            ...(opts.newest ? { newest: true } : {}),
+        }), command);
+    });
+    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) => {
+        const event = reference === undefined ? undefined : eventIdOf(reference);
+        const filter = event === undefined
+            ? await eventsFilter(["week"], { store: deps.store, accountId: deps.accountId, zone: zone(), now: now() })
+            : undefined;
+        print(await peopleAnswer(deps.store, deps.accountId, {
+            ...(event === undefined ? {} : { event }),
+            ...(filter ? { filter } : {}),
+            ...(personOfEmail ? { personOf: personOfEmail } : {}),
+        }), command);
+    });
+    output(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) => {
+        const linked = await linkPeople(messages("people link"), deps.account, person, other);
+        print({
+            person: `person:${linked.uid}`,
+            name: linked.name,
+            identities: linked.identities.map(({ provider, id }) => `${provider}:${id}`),
+        }, command);
+    });
+    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) => {
+        print(await reviewsAnswer(deps.store), command);
+    });
+    output(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) => {
+        print(await resolveAnswer(deps.store, review, choice, now()), command);
+    });
+};
+export const addCalendarCommands = sharedCommand(addCalendarCommandsDefinition);

package/dist/calendar/index.d.ts

@@ -0,0 +1,3 @@
+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 type { CalendarExpander, CalendarSource, CalendarSourceTraits, ChangePage, ChangeResult, SyncWindow, } from "./source.js";
+export { type CalendarCursor, type CalendarSyncOptions, type CalendarSyncReport, type CalendarSyncResult, calendarSyncWindow, parseCalendarCursor, syncCalendars, } from "./sync.js";

package/dist/calendar/index.js

@@ -0,0 +1 @@
+export { calendarSyncWindow, parseCalendarCursor, syncCalendars, } from "./sync.js";

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

@@ -0,0 +1,307 @@
+import { type FailureContext } from "@wirecat/cli-base";
+import { type EventStore } from "../../meetings/index.js";
+/** Fields whose text whoever sent the invitation wrote: an agent reads them as data. */
+export declare const CALENDAR_UNTRUSTED_FIELDS: string[];
+export declare const calendarTools: ({
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            account_id: {
+                type: string;
+                minimum: number;
+            };
+            words?: undefined;
+            timezone?: undefined;
+            limit?: undefined;
+            event?: undefined;
+        } | {
+            account_id: {
+                type: string;
+                minimum: number;
+            };
+            words: {
+                type: string;
+                minLength: number;
+            };
+            timezone: {
+                type: string;
+                minLength: number;
+            };
+            limit: {
+                type: string;
+                minimum: number;
+                maximum: number;
+            };
+            event?: undefined;
+        } | {
+            words?: undefined;
+            timezone?: undefined;
+            limit?: undefined;
+            event: {
+                type: string;
+                minLength: number;
+            };
+            account_id: {
+                type: string;
+                minimum: number;
+            };
+        } | {
+            words?: undefined;
+            timezone?: undefined;
+            limit?: undefined;
+            event?: undefined;
+            account_id?: undefined;
+        };
+        required: string[] | never[];
+        additionalProperties: boolean;
+    };
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            account_id: {
+                type: string;
+                minimum: number;
+            };
+            words?: undefined;
+            timezone?: undefined;
+            limit?: undefined;
+            event?: undefined;
+        } | {
+            account_id: {
+                type: string;
+                minimum: number;
+            };
+            words: {
+                type: string;
+                minLength: number;
+            };
+            timezone: {
+                type: string;
+                minLength: number;
+            };
+            limit: {
+                type: string;
+                minimum: number;
+                maximum: number;
+            };
+            event?: undefined;
+        } | {
+            words?: undefined;
+            timezone?: undefined;
+            limit?: undefined;
+            event: {
+                type: string;
+                minLength: number;
+            };
+            account_id: {
+                type: string;
+                minimum: number;
+            };
+        } | {
+            words?: undefined;
+            timezone?: undefined;
+            limit?: undefined;
+            event?: undefined;
+            account_id?: undefined;
+        };
+        required: string[] | never[];
+        additionalProperties: boolean;
+    };
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            account_id: {
+                type: string;
+                minimum: number;
+            };
+            words?: undefined;
+            timezone?: undefined;
+            limit?: undefined;
+            event?: undefined;
+        } | {
+            account_id: {
+                type: string;
+                minimum: number;
+            };
+            words: {
+                type: string;
+                minLength: number;
+            };
+            timezone: {
+                type: string;
+                minLength: number;
+            };
+            limit: {
+                type: string;
+                minimum: number;
+                maximum: number;
+            };
+            event?: undefined;
+        } | {
+            words?: undefined;
+            timezone?: undefined;
+            limit?: undefined;
+            event: {
+                type: string;
+                minLength: number;
+            };
+            account_id: {
+                type: string;
+                minimum: number;
+            };
+        } | {
+            words?: undefined;
+            timezone?: undefined;
+            limit?: undefined;
+            event?: undefined;
+            account_id?: undefined;
+        };
+        required: string[] | never[];
+        additionalProperties: boolean;
+    };
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            account_id: {
+                type: string;
+                minimum: number;
+            };
+            words?: undefined;
+            timezone?: undefined;
+            limit?: undefined;
+            event?: undefined;
+        } | {
+            account_id: {
+                type: string;
+                minimum: number;
+            };
+            words: {
+                type: string;
+                minLength: number;
+            };
+            timezone: {
+                type: string;
+                minLength: number;
+            };
+            limit: {
+                type: string;
+                minimum: number;
+                maximum: number;
+            };
+            event?: undefined;
+        } | {
+            words?: undefined;
+            timezone?: undefined;
+            limit?: undefined;
+            event: {
+                type: string;
+                minLength: number;
+            };
+            account_id: {
+                type: string;
+                minimum: number;
+            };
+        } | {
+            words?: undefined;
+            timezone?: undefined;
+            limit?: undefined;
+            event?: undefined;
+            account_id?: undefined;
+        };
+        required: string[] | never[];
+        additionalProperties: boolean;
+    };
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+})[];
+/**
+ * Runs one calendar tool over the accounts the host serves. Without `account_id` a tool reads every one of them and
+ * names them in `accounts`; with one it must be among them.
+ */
+export declare const callCalendarTool: (store: EventStore, name: string, input: unknown, { accountIds, failure, now, }: {
+    accountIds: readonly number[];
+    failure?: FailureContext;
+    now?: number;
+}) => Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent: {
+        error: {
+            code: "authentication_error" | "cancelled" | "configuration_error" | "confirmation_required" | "internal_error" | "invalid_response" | "network_error" | "not_found" | "outcome_unknown" | "permission_error" | "provider_error" | "provider_unavailable" | "rate_limited" | "timeout" | "validation_error";
+            reason: string;
+            message: string;
+            param?: string | undefined;
+            details?: {
+                [x: string]: unknown;
+            } | undefined;
+            next?: ({
+                kind: "command";
+                step: string;
+                command: string;
+                args: {
+                    [x: string]: unknown;
+                };
+                line?: string | undefined;
+                why: string;
+                safe_to_auto_execute: boolean;
+            } | {
+                kind: "user_action";
+                step: string;
+                why: string;
+                safe_to_auto_execute: false;
+            })[] | undefined;
+            retry: {
+                safe: boolean;
+                after_ms?: number | undefined;
+            };
+            run_id?: string | undefined;
+        };
+    };
+    isError: true;
+} | ({
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent: {
+        accounts: number[];
+        untrusted: string[];
+    };
+} & {
+    isError?: boolean;
+})>;