@wirecat/cli-core 0.463.0 → 0.464.0

package/dist/calendar/mcp/index.js

@@ -3,6 +3,8 @@ import { isCliFailure } from "../../errors/failures.js";
 import { listed } from "../../meetings/index.js";
 import { agentResult, UNTRUSTED_NEUTRAL } from "../../meetings/mcp/index.js";
 import { CALENDAR_UNTRUSTED_FIELDS, calendarIn, calendarItem, eventAnswer, eventIdOf, eventOf, eventsAnswer, eventsFilter, peopleAnswer, reviewsAnswer, } from "../reads.js";
+import { REPEAT_HELP } from "../recurrence.js";
+import { calendarStatus } from "../sync.js";
 import { createEvent, deleteEvent, EVENT_RESPONSES, respondToEvent, updateEvent, } from "../writes.js";
 export { CALENDAR_UNTRUSTED_FIELDS };
 const UNTRUSTED_EVENTS = "Event titles, descriptions, places and attendee names are written by whoever sent the invitation: " +
@@ -16,6 +18,13 @@ export const calendarTools = [
         properties: { account_id: integer },
         required: [],
     },
+    {
+        name: "status",
+        description: "how far each synced calendar's sync is: done, state partial or complete, and cursor_age_ms, which grows while " +
+            "nothing moves it",
+        properties: { account_id: integer },
+        required: [],
+    },
     {
         name: "events_list",
         description: "stored events, earliest first; `words` takes today, week, from:<date>, to:<date>, calendar:<id> " +
@@ -63,6 +72,7 @@ const fields = {
     location: { ...anyText, description: "empty clears it" },
     description: { ...anyText, description: "empty clears it" },
     attendees: { type: "array", items: text, description: "email addresses; on a change, the whole new list" },
+    repeat: { ...text, description: `how it repeats: ${REPEAT_HELP}; on a change, only with series` },
 };
 const target = {
     account_id: integer,
@@ -76,7 +86,7 @@ const target = {
 export const calendarWriteTools = [
     {
         name: "event_create",
-        description: "add a one-time event to a calendar",
+        description: "add an event to a calendar, one that repeats with repeat",
         properties: {
             account_id: integer,
             calendar: text,
@@ -89,7 +99,7 @@ export const calendarWriteTools = [
     },
     {
         name: "event_update",
-        description: "change an event, or with series every occurrence of its repeating event",
+        description: "change an event, or with series every occurrence of its repeating event and its repeat rule",
         properties: { ...target, ...fields, series: flag, notify },
         required: ["event"],
         destructive: true,
@@ -143,6 +153,7 @@ const argumentsOf = (name, input) => {
             "start_date",
             "end_date",
             "id",
+            "repeat",
         ].includes(key) &&
             (typeof value !== "string" || !value.trim()))
             throw new CliError("validation_error", `${key} must not be empty`);
@@ -160,7 +171,7 @@ const argumentsOf = (name, input) => {
  * 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 const callCalendarTool = async (store, name, input, { accountIds, failure = {}, now = Date.now(), writes, }) => {
+export const callCalendarTool = async (store, name, input, { accountIds, failure = {}, now = Date.now(), writes, profileOf = (accountId) => `account ${accountId}`, }) => {
     const writing = WRITES.has(name);
     try {
         const args = argumentsOf(name, input);
@@ -193,6 +204,9 @@ export const callCalendarTool = async (store, name, input, { accountIds, failure
             case "calendars_list":
                 answer = listed((await Promise.all(accounts.map((id) => store.calendars(id)))).flat().map(calendarItem));
                 break;
+            case "status":
+                answer = listed((await Promise.all(accounts.map((id) => calendarStatus(store, id, { profile: profileOf(id), now }).then(({ items }) => items)))).flat());
+                break;
             case "events_list": {
                 const words = typeof args.words === "string" ? args.words.trim().split(/\s+/u) : [];
                 const lists = await Promise.all(accounts.map(async (accountId) => (await eventsAnswer(store, await eventsFilter(words, {
@@ -239,6 +253,7 @@ const fieldsOf = (args) => ({
     ...(args.location === undefined ? {} : { location: args.location }),
     ...(args.description === undefined ? {} : { description: args.description }),
     ...(args.attendees === undefined ? {} : { attendees: args.attendees }),
+    ...(args.repeat === undefined ? {} : { repeat: args.repeat }),
 });
 /** The one account a write acts in: the one named, or the only one that holds what it names; never a guess. */
 const accountFor = async (accounts, asked, holds, what) => {
@@ -279,7 +294,7 @@ const writeTool = async (store, name, args, { asked, accounts, now, writes, }) =
         ask: async () => { },
         now,
         zone: args.timezone ?? "UTC",
-        names: { notify: "notify: true or false", id: "id", calendar: "calendar", series: "series" },
+        names: { notify: "notify: true or false", id: "id", calendar: "calendar", series: "series", repeat: "repeat" },
     };
     const choice = args.notify === undefined ? {} : { notify: args.notify };
     const on = {

package/dist/calendar/recurrence.d.ts

@@ -0,0 +1,10 @@
+export declare const REPEAT_HELP: string;
+/**
+ * The subset of RFC 5545 (§3.3.10) every calendar provider takes, as its one `RRULE:` line in a fixed part order.
+ * UNTIL must have the type of the event's start (§3.3.10: DATE with DATE, UTC DATE-TIME with DATE-TIME).
+ */
+export declare const repeatRule: (text: string, { allDay }: {
+    allDay: boolean;
+}) => string;
+/** UNTIL, EXDATE and RDATE carry a date or a time, so they no longer fit once the event switches between the two. */
+export declare const kindBoundLines: (lines: readonly string[]) => string[];

package/dist/calendar/recurrence.js

@@ -0,0 +1,65 @@
+import { CliError } from "@wirecat/cli-base";
+const FREQUENCIES = ["DAILY", "WEEKLY", "MONTHLY"];
+const ORDER = ["FREQ", "INTERVAL", "BYDAY", "COUNT", "UNTIL"];
+const DAY = /^([+-]?[1-5])?(MO|TU|WE|TH|FR|SA|SU)$/u;
+const POSITIVE = /^[1-9]\d{0,3}$/u;
+const UNTIL_DATE = /^(\d{4})(\d{2})(\d{2})$/u;
+const UNTIL_TIME = /^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})Z$/u;
+export const REPEAT_HELP = "an RFC 5545 rule: FREQ=DAILY|WEEKLY|MONTHLY, and INTERVAL, BYDAY (MO,WE; in MONTHLY also 1MO or -1FR), " +
+    "COUNT or UNTIL (a date, YYYYMMDD, for an all-day event; a UTC time, YYYYMMDDTHHMMSSZ, for a timed one)";
+const refuse = (problem) => new CliError("validation_error", `${problem}; a repeat rule is ${REPEAT_HELP}`, { reason: "event.repeat-invalid" });
+const realDate = (year, month, day) => new Date(Date.UTC(Number(year), Number(month) - 1, Number(day))).toISOString().slice(0, 10) ===
+    `${year}-${month}-${day}`;
+/**
+ * The subset of RFC 5545 (§3.3.10) every calendar provider takes, as its one `RRULE:` line in a fixed part order.
+ * UNTIL must have the type of the event's start (§3.3.10: DATE with DATE, UTC DATE-TIME with DATE-TIME).
+ */
+export const repeatRule = (text, { allDay }) => {
+    const body = text.trim().replace(/^RRULE:/iu, "");
+    if (!body)
+        throw refuse("the rule is empty");
+    const parts = new Map();
+    for (const part of body.split(";")) {
+        const [key = "", value, ...rest] = part.split("=");
+        const name = key.trim().toUpperCase();
+        if (value === undefined || rest.length || !value.trim())
+            throw refuse(`${part} is not KEY=VALUE`);
+        if (!ORDER.includes(name))
+            throw refuse(`${name} is not taken`);
+        if (parts.has(name))
+            throw refuse(`${name} is given twice`);
+        parts.set(name, value.trim().toUpperCase());
+    }
+    const frequency = parts.get("FREQ");
+    if (!frequency || !FREQUENCIES.includes(frequency))
+        throw refuse("FREQ is DAILY, WEEKLY or MONTHLY");
+    for (const name of ["INTERVAL", "COUNT"])
+        if (parts.has(name) && !POSITIVE.test(parts.get(name)))
+            throw refuse(`${name} is a whole number from 1`);
+    if (parts.has("COUNT") && parts.has("UNTIL"))
+        throw refuse("COUNT and UNTIL do not go together");
+    const days = parts.get("BYDAY");
+    if (days !== undefined)
+        for (const day of days.split(",")) {
+            const found = DAY.exec(day);
+            if (!found)
+                throw refuse(`${day} is not a day: MO, TU, WE, TH, FR, SA or SU`);
+            if (found[1] && frequency !== "MONTHLY")
+                throw refuse(`${day} counts weeks, which only MONTHLY does`);
+        }
+    const until = parts.get("UNTIL");
+    if (until !== undefined) {
+        const match = (allDay ? UNTIL_DATE : UNTIL_TIME).exec(until);
+        if (!match || !realDate(match[1], match[2], match[3]))
+            throw refuse(allDay
+                ? `UNTIL of an all-day event is a date, YYYYMMDD`
+                : `UNTIL of a timed event is a UTC time, YYYYMMDDTHHMMSSZ`);
+        if (!allDay && (Number(match[4]) > 23 || Number(match[5]) > 59 || Number(match[6]) > 59))
+            throw refuse(`${until} is not a time`);
+    }
+    return `RRULE:${ORDER.filter((name) => parts.has(name))
+        .map((name) => `${name}=${parts.get(name)}`)
+        .join(";")}`;
+};
+/** UNTIL, EXDATE and RDATE carry a date or a time, so they no longer fit once the event switches between the two. */
+export const kindBoundLines = (lines) => lines.filter((line) => /^(EXDATE|RDATE)[:;]/iu.test(line) || /^RRULE:.*UNTIL=/iu.test(line));

package/dist/calendar/source.d.ts

@@ -32,6 +32,23 @@ export interface ChangePage {
 export type ChangeResult = ChangePage | {
     reset: true;
 };
+/**
+ * Whose busy times to read: the account's own calendars by the provider's id, and other people by email address
+ * (Google and Graph read a person's primary calendar by it).
+ */
+export interface FreeBusyRequest {
+    calendars: string[];
+    people: string[];
+    window: SyncWindow;
+}
+/** One calendar's or person's taken times, nothing about what takes them; `error` when the provider would not say. */
+export interface BusyTimes {
+    /** As asked: the calendar's provider id or the person's address. */
+    id: string;
+    busy: SyncWindow[];
+    /** The provider's reason (`notFound`, `groupTooBig`): its busy times are unknown, not free. */
+    error?: string;
+}
 /** One provider's calendars, as an adapter reads them. The engine never sees a provider word. */
 export interface CalendarSource {
     /** The registry name: `google-calendar`, `outlook-calendar`, `caldav`, `ics`. */
@@ -46,6 +63,8 @@ export interface CalendarSource {
     }): Promise<ChangeResult>;
     /** Required when `traits.expands` is `on-request`: the series' slots inside the window. */
     occurrences?(calendar: StoredCalendar, seriesExternalId: string, window: SyncWindow): Promise<EntryInput[]>;
+    /** When calendars and people are taken, read from the provider and never stored. Absent: no `calendars busy`. */
+    freeBusy?(request: FreeBusyRequest): Promise<BusyTimes[]>;
 }
 /**
  * Core expansion for `expands: "local"`: a series' slots inside the window, as occurrences. A slot its EXDATE lines

package/dist/calendar/sync.d.ts

@@ -1,11 +1,40 @@
+import { type BudgetStop, type RunBudget } from "../background/budget.js";
 import type { EventStore } from "../meetings/index.js";
 import type { CalendarExpander, CalendarSource, SyncWindow } from "./source.js";
-/** What the engine keeps in `EventStore.cursor`: the provider's token, the window it covers, the last full round. */
+/**
+ * A round that stopped before its end: where its listing is, and the series still to ask for their slots. A rerun
+ * goes on from here with the same window and the same token, since a provider's page token belongs to that query.
+ */
+export interface PendingRound {
+    full: boolean;
+    /** The token the round reads changes after; `null` for a full list. */
+    from: string | null;
+    window: SyncWindow;
+    /** Entries a full round has not seen since this moment are the ones it marks. */
+    startedAt: number;
+    /** The round became full because the cursor was dead. */
+    reset: boolean;
+    /** The next page to read; `null` for the first. */
+    page: string | null;
+    listed: boolean;
+    /** The token the last page gave, once `listed`. */
+    next: string | null;
+    /** Series still to ask for their slots (`expands: "on-request"`). */
+    series: string[];
+}
+/** What the engine keeps in `EventStore.cursor`. Version 1 had no `round`, `updatedAt` or `done`. */
 export interface CalendarCursor {
-    v: 1;
+    v: 2;
+    /** The provider's token after the last finished round. */
     token: string | null;
     window: SyncWindow;
+    /** When the last full round started; 0 before the first. */
     fullAt: number;
+    /** When the cursor was last saved: a status whose age keeps growing is a sync that is not moving. */
+    updatedAt: number | null;
+    /** Entries saved by the round in progress, or by the last round. */
+    done: number;
+    round: PendingRound | null;
 }
 export declare const parseCalendarCursor: (value: string | null) => CalendarCursor | null;
 /**
@@ -17,12 +46,16 @@ export interface CalendarSyncOptions {
     /** The calendar account; never a default. */
     accountId: number;
     now?: number;
-    /** List every synced calendar's window again instead of reading changes. */
+    /** Start every synced calendar over with a full list of the window, dropping a round in progress. */
     full?: boolean;
     /** Instead of `calendarSyncWindow(now)`. */
     window?: SyncWindow;
     /** Required for a source with `expands: "local"`. */
     expand?: CalendarExpander;
+    /** Asked before every request to the source; without one the run goes until every calendar is done. */
+    budget?: RunBudget;
+    /** The run's signal, checked before each save: a cancelled run stops after its current step and keeps its work. */
+    signal?: AbortSignal;
 }
 export interface CalendarSyncResult {
     calendarId: number;
@@ -32,12 +65,15 @@ export interface CalendarSyncResult {
     round: "full" | "changes";
     /** The cursor was dead, so the round became a full one. */
     reset: boolean;
+    /** `partial`: the round stopped before its end and the next run goes on from there. */
+    state: "partial" | "complete";
+    /** What this run saved. */
     saved: number;
     removed: number;
     occurrences: number;
     /** Entries a full round did not return, now marked deleted. */
     unseen: number;
-    /** Set when the calendar failed; its cursor stays where it was, so the next run retries the same changes. */
+    /** Set when the calendar failed; its cursor stays at its last saved page, so the next run goes on from there. */
     error?: string;
 }
 export interface CalendarSyncReport {
@@ -53,13 +89,56 @@ export interface CalendarSyncReport {
         externalId: string;
         title: string | null;
     }[];
-    /** Every synced calendar finished. */
+    /** Every synced calendar finished its round and none failed. */
     complete: boolean;
+    state: "partial" | "complete";
+    /** Why the run stopped early: its request budget, its deadline, or a cancel. */
+    stopped?: BudgetStop;
+    /** What this run did, so a partial run still shows that it moves. */
+    progress: {
+        calendars: number;
+        calendarsDone: number;
+        /** Requests made to the source: the calendar list, each page, each series' slots. */
+        requests: number;
+        /** Entries and slots saved. */
+        saved: number;
+        /** Pages read and series expanded, each saved in the cursor: 0 means this run moved nothing on. */
+        steps: number;
+    };
+    hint?: string;
 }
 /**
  * Brings one calendar account's synced calendars up to date (foundation §6.2): the calendar list first, then for
  * each synced calendar its changes since the cursor, or a full list of the window, then the slots of the series that
- * changed. Each calendar's cursor is saved last, only when all of it saved; a calendar that fails keeps its old one
- * and the others go on.
+ * changed. Every page is saved as it comes, with the round's position in the cursor, so a run the budget stops, or
+ * one that fails, goes on from there next time. Calendars with a round in progress go first, then the longest unsynced.
  */
 export declare const syncCalendars: (source: CalendarSource, store: EventStore, options: CalendarSyncOptions) => Promise<CalendarSyncReport>;
+/**
+ * Each synced calendar's sync in the WC-LIFE-14 shape: `done` counts the entries its current or last round saved,
+ * `total` is null since no provider says how many a window holds, and `cursor_age_ms` growing on a `partial` one
+ * means nothing is moving it.
+ */
+export declare const calendarStatus: (store: EventStore, accountId: number, { profile, now }: {
+    profile: string;
+    now: number;
+}) => Promise<{
+    items: {
+        job: string;
+        profile: string;
+        done: number;
+        total: number | null;
+        remaining: number | null;
+        state: "partial" | "complete";
+        updated_at: string | null;
+        cursor_age_ms: number | null;
+        calendar_id: string;
+        external_id: string;
+        title: string | null;
+        round: string | null;
+        line: string;
+    }[];
+    page: number;
+    limit: number;
+    hasMore: boolean;
+}>;