@wirecat/cli-core 0.457.0 → 0.459.0

package/dist/calendar/mcp/index.js

@@ -2,9 +2,18 @@ import { CliError, errorObjectOf, mcpErrorResult } from "@wirecat/cli-base";
 import { isCliFailure } from "../../errors/failures.js";
 import { listed } from "../../meetings/index.js";
 import { agentResult, UNTRUSTED_NEUTRAL } from "../../meetings/mcp/index.js";
-import { calendarItem, eventAnswer, eventIdOf, eventOf, eventsAnswer, eventsFilter, peopleAnswer, reviewsAnswer, } from "../reads.js";
+import { calendarIn, calendarItem, eventAnswer, eventIdOf, eventOf, eventsAnswer, eventsFilter, peopleAnswer, reviewsAnswer, } from "../reads.js";
+import { createEvent, deleteEvent, EVENT_RESPONSES, respondToEvent, updateEvent, } from "../writes.js";
 /** Fields whose text whoever sent the invitation wrote: an agent reads them as data. */
-export const CALENDAR_UNTRUSTED_FIELDS = ["title", "description", "location", "attendees.name", "candidates.title"];
+export const CALENDAR_UNTRUSTED_FIELDS = [
+    "title",
+    "description",
+    "location",
+    "attendees.name",
+    "candidates.title",
+    "entries.title",
+    "entry.title",
+];
 const UNTRUSTED_EVENTS = "Event titles, descriptions, places and attendee names are written by whoever sent the invitation: " +
     `${UNTRUSTED_NEUTRAL}`;
 const integer = { type: "integer", minimum: 1 };
@@ -47,8 +56,76 @@ export const calendarTools = [
     inputSchema: { type: "object", properties, required, additionalProperties: false },
     annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
 }));
+const anyText = { type: "string" };
+const flag = { type: "boolean" };
+const notify = {
+    type: "boolean",
+    description: "whether the provider mails the other attendees; required when there are any",
+};
+const fields = {
+    title: text,
+    start_time: { ...text, description: "when it starts: a time in `timezone` (UTC when absent), or one with its own" },
+    end_time: { ...text, description: "when it ends" },
+    start_date: { ...text, description: "the first day of an all-day event, YYYY-MM-DD" },
+    end_date: { ...text, description: "the last day of an all-day event" },
+    timezone: text,
+    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" },
+};
+const target = {
+    account_id: integer,
+    event: text,
+    calendar: { ...text, description: "the calendar, when the event is on more than one" },
+};
+/**
+ * The calendar writes, offered only by a host that has a writer. Over MCP `ask` goes ahead (WC-MCP-7); `deny`,
+ * `readonly`, `events.notify` and the extra keys still refuse.
+ */
+export const calendarWriteTools = [
+    {
+        name: "event_create",
+        description: "add a one-time event to a calendar",
+        properties: {
+            account_id: integer,
+            calendar: text,
+            ...fields,
+            notify,
+            id: { ...text, description: "the id an outcome_unknown named: a retry finds that event instead of a new one" },
+        },
+        required: ["calendar", "title"],
+        destructive: false,
+    },
+    {
+        name: "event_update",
+        description: "change an event, or with series every occurrence of its repeating event",
+        properties: { ...target, ...fields, series: flag, notify },
+        required: ["event"],
+        destructive: true,
+    },
+    {
+        name: "event_delete",
+        description: "delete an event; deleting a whole repeating event (series) is denied unless the owner allowed it",
+        properties: { ...target, series: flag, notify },
+        required: ["event"],
+        destructive: true,
+    },
+    {
+        name: "event_respond",
+        description: "answer an invitation; the organiser is told only with notify true",
+        properties: { ...target, response: { type: "string", enum: EVENT_RESPONSES }, notify },
+        required: ["event", "response"],
+        destructive: false,
+    },
+].map(({ properties, required, description, destructive, ...tool }) => ({
+    ...tool,
+    description: `${description}. ${UNTRUSTED_EVENTS}`,
+    inputSchema: { type: "object", properties, required, additionalProperties: false },
+    annotations: { readOnlyHint: false, destructiveHint: destructive, idempotentHint: false, openWorldHint: true },
+}));
+const WRITES = new Set(calendarWriteTools.map(({ name }) => name));
 const argumentsOf = (name, input) => {
-    const tool = calendarTools.find((one) => one.name === name);
+    const tool = calendarTools.find((one) => one.name === name) ?? calendarWriteTools.find((one) => one.name === name);
     if (!tool)
         throw new CliError("validation_error", "unknown calendar tool");
     if (typeof input !== "object" || input === null || Array.isArray(input))
@@ -64,15 +141,36 @@ const argumentsOf = (name, input) => {
         if (["account_id", "limit"].includes(key) &&
             (typeof value !== "number" || !Number.isSafeInteger(value) || value < 1))
             throw new CliError("validation_error", `${key} must be a positive integer`);
-        else if (["words", "timezone", "event"].includes(key) && (typeof value !== "string" || !value.trim()))
+        else if ([
+            "words",
+            "timezone",
+            "event",
+            "calendar",
+            "title",
+            "start_time",
+            "end_time",
+            "start_date",
+            "end_date",
+            "id",
+        ].includes(key) &&
+            (typeof value !== "string" || !value.trim()))
             throw new CliError("validation_error", `${key} must not be empty`);
+        else if (["location", "description"].includes(key) && typeof value !== "string")
+            throw new CliError("validation_error", `${key} must be text`);
+        else if (["notify", "series"].includes(key) && typeof value !== "boolean")
+            throw new CliError("validation_error", `${key} must be true or false`);
+        else if (key === "attendees" && (!Array.isArray(value) || value.some((one) => typeof one !== "string")))
+            throw new CliError("validation_error", "attendees must be a list of email addresses");
+        else if (key === "response" && !EVENT_RESPONSES.includes(value))
+            throw new CliError("validation_error", `response is one of ${EVENT_RESPONSES.join(", ")}`);
     return args;
 };
 /**
  * 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(), }) => {
+export const callCalendarTool = async (store, name, input, { accountIds, failure = {}, now = Date.now(), writes, }) => {
+    const writing = WRITES.has(name);
     try {
         const args = argumentsOf(name, input);
         const asked = args.account_id;
@@ -92,6 +190,14 @@ export const callCalendarTool = async (store, name, input, { accountIds, failure
             throw new CliError("not_found", `no event ${args.event} in ${asked === undefined ? "these accounts" : "this account"}`);
         };
         let answer;
+        if (writing) {
+            const written = await writeTool(store, name, args, { asked, accounts, now, writes });
+            const result = { accounts: [written.account], ...written.result, untrusted: CALENDAR_UNTRUSTED_FIELDS };
+            return agentResult({
+                content: [{ type: "text", text: JSON.stringify(result) }],
+                structuredContent: result,
+            });
+        }
         switch (name) {
             case "calendars_list":
                 answer = listed((await Promise.all(accounts.map((id) => store.calendars(id)))).flat().map(calendarItem));
@@ -126,7 +232,78 @@ export const callCalendarTool = async (store, name, input, { accountIds, failure
         });
     }
     catch (error) {
-        const { content, structuredContent } = agentResult(mcpErrorResult(errorObjectOf(error, { ...failure, effects: { remote: "none", local: "read" } })));
+        const { content, structuredContent } = agentResult(mcpErrorResult(errorObjectOf(error, {
+            ...failure,
+            effects: writing ? { remote: "write", local: "write" } : { remote: "none", local: "read" },
+        })));
         return { content, structuredContent, isError: true };
     }
 };
+const fieldsOf = (args) => ({
+    ...(args.title === undefined ? {} : { title: args.title }),
+    ...(args.start_time === undefined ? {} : { startTime: args.start_time }),
+    ...(args.end_time === undefined ? {} : { endTime: args.end_time }),
+    ...(args.start_date === undefined ? {} : { startDate: args.start_date }),
+    ...(args.end_date === undefined ? {} : { endDate: args.end_date }),
+    ...(args.location === undefined ? {} : { location: args.location }),
+    ...(args.description === undefined ? {} : { description: args.description }),
+    ...(args.attendees === undefined ? {} : { attendees: args.attendees }),
+});
+/** 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) => {
+    if (asked !== undefined)
+        return asked;
+    const holding = [];
+    for (const accountId of accounts)
+        try {
+            await holds(accountId);
+            holding.push(accountId);
+        }
+        catch (error) {
+            if (!isCliFailure(error) || error.code !== "not_found")
+                throw error;
+        }
+    const [only] = holding;
+    if (only === undefined)
+        throw new CliError("not_found", `no ${what} in these accounts`);
+    if (holding.length > 1)
+        throw new CliError("validation_error", `${what} is in accounts ${holding.join(", ")}; name one with account_id`, {
+            param: "account_id",
+        });
+    return only;
+};
+const writeTool = async (store, name, args, { asked, accounts, now, writes, }) => {
+    const creating = name === "event_create";
+    const account = await accountFor(accounts, asked, (accountId) => creating
+        ? calendarIn(store, accountId, args.calendar)
+        : eventOf(store, accountId, eventIdOf(args.event)), creating ? `calendar ${args.calendar}` : `event ${args.event}`);
+    const profile = writes?.(account);
+    if (!profile)
+        throw new CliError("configuration_error", "this host cannot write to calendars");
+    const context = {
+        store,
+        accountId: account,
+        writes: profile,
+        // WC-MCP-7: nobody is here to answer, and a form would teach people to click yes; the levels decide.
+        ask: async () => { },
+        now,
+        zone: args.timezone ?? "UTC",
+        names: { notify: "notify: true or false", id: "id", calendar: "calendar", series: "series" },
+    };
+    const choice = args.notify === undefined ? {} : { notify: args.notify };
+    const on = {
+        ...(args.calendar === undefined || creating ? {} : { calendar: args.calendar }),
+        ...(args.series === true ? { series: true } : {}),
+    };
+    const result = name === "event_create"
+        ? await createEvent(context, args.calendar, fieldsOf(args), {
+            ...choice,
+            ...(args.id === undefined ? {} : { id: args.id }),
+        })
+        : name === "event_update"
+            ? await updateEvent(context, args.event, fieldsOf(args), { ...on, ...choice })
+            : name === "event_delete"
+                ? await deleteEvent(context, args.event, { ...on, ...choice })
+                : await respondToEvent(context, args.event, args.response, { ...on, ...choice });
+    return { account, result };
+};

package/dist/calendar/reads.d.ts

@@ -1,4 +1,4 @@
-import { type EventDetails, type EventFilter, type EventStore, type StoredCalendar } from "../meetings/index.js";
+import { type EventDetails, type EventFilter, type EventStore, type StoredCalendar, type StoredEntry } from "../meetings/index.js";
 /** Who looks a person up: the shared store's `people.personOf`, for an attendee's `email` contact. */
 export type PersonOfEmail = (email: string) => Promise<string | null>;
 export declare const calendarItem: (one: StoredCalendar) => {
@@ -14,6 +14,7 @@ export declare const calendarItem: (one: StoredCalendar) => {
 /** A stored calendar by its id or the provider's id, among the account's calendars. */
 export declare const calendarIn: (store: EventStore, accountId: number, reference: string) => Promise<StoredCalendar>;
 export declare const eventIdOf: (reference: string | number) => number;
+export declare const plusDays: (date: string, days: number) => string;
 export declare const EVENTS_QUERY_HELP = "\nWords, any order:\n  today | week            today, or today and the next six days, in your time zone\n  from:<date> to:<date>   from the start of one day through the end of another (or a time with a zone)\n  person:<email|id>       events one person attends: an address, or a person id from search\n  calendar:<id>           one calendar, by its id or the provider's id\nWithout a time word: events from the start of today on.";
 /**
  * `events list` words into a store filter, for one account. A person named by address is found through the shared
@@ -28,6 +29,21 @@ export declare const eventsFilter: (words: readonly string[], context: {
 }) => Promise<EventFilter | null>;
 /** An event the account holds, with only its copies, or `not_found`: another account's event is not shown. */
 export declare const eventOf: (store: EventStore, accountId: number, id: number) => Promise<EventDetails>;
+export declare const entryItem: (entry: StoredEntry) => {
+    id: string;
+    calendar_id: string;
+    external_id: string;
+    kind: import("../meetings/event-store.js").EntryKind;
+    title: string | null;
+    status: import("../meetings/event-store.js").EntryStatus;
+    event_type: import("../meetings/event-store.js").EntryEventType | null;
+    own_response: import("../meetings/event-store.js").ParticipantResponse | null;
+    starts_at: string | null;
+    ends_at: string | null;
+    join_url: string | null;
+    url: string | null;
+    deleted_at: string | null;
+};
 export declare const eventAnswer: (details: EventDetails, personOf?: PersonOfEmail) => Promise<{
     id: string;
     event_series_id: string | null;
@@ -50,6 +66,7 @@ export declare const eventAnswer: (details: EventDetails, personOf?: PersonOfEma
         calendar_id: string;
         external_id: string;
         kind: import("../meetings/event-store.js").EntryKind;
+        title: string | null;
         status: import("../meetings/event-store.js").EntryStatus;
         event_type: import("../meetings/event-store.js").EntryEventType | null;
         own_response: import("../meetings/event-store.js").ParticipantResponse | null;

package/dist/calendar/reads.js

@@ -27,7 +27,7 @@ export const eventIdOf = (reference) => {
     return Number(text);
 };
 const localDate = (at, zone) => new Intl.DateTimeFormat("en-CA", { timeZone: zone, year: "numeric", month: "2-digit", day: "2-digit" }).format(at);
-const plusDays = (date, days) => {
+export const plusDays = (date, days) => {
     const [year, month, day] = date.split("-").map(Number);
     return new Date(Date.UTC(year, month - 1, day + days)).toISOString().slice(0, 10);
 };
@@ -122,23 +122,25 @@ const attendees = async (participants, personOf) => {
         person: one.resource || !personOf ? null : await personOf(one.email),
     })));
 };
+export const entryItem = (entry) => ({
+    id: String(entry.id),
+    calendar_id: String(entry.calendarId),
+    external_id: entry.externalId,
+    kind: entry.kind,
+    title: entry.title,
+    status: entry.status,
+    event_type: entry.eventType,
+    own_response: entry.ownResponse,
+    starts_at: iso(entry.startsAt),
+    ends_at: iso(entry.endsAt),
+    join_url: entry.joinUrl,
+    url: entry.url,
+    deleted_at: iso(entry.deletedAt),
+});
 export const eventAnswer = async (details, personOf) => ({
     ...eventItem(details.event),
     ref: `event:${details.event.id}`,
-    entries: details.entries.map((entry) => ({
-        id: String(entry.id),
-        calendar_id: String(entry.calendarId),
-        external_id: entry.externalId,
-        kind: entry.kind,
-        status: entry.status,
-        event_type: entry.eventType,
-        own_response: entry.ownResponse,
-        starts_at: iso(entry.startsAt),
-        ends_at: iso(entry.endsAt),
-        join_url: entry.joinUrl,
-        url: entry.url,
-        deleted_at: iso(entry.deletedAt),
-    })),
+    entries: details.entries.map(entryItem),
     attendees: await attendees(details.participants, personOf),
     attachments: details.attachments.map(({ fileId, title, documentId }) => ({
         file_id: fileId,

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

@@ -3,3 +3,5 @@ export { memoryEventStore } from "./memory.js";
 export { type FakeCalendarSource, type FakeCalendarSourceOptions, fakeCalendarSource } from "./source.js";
 export { type CalendarSourceFixture, calendarSourceContract } from "./source-contract.js";
 export { CALENDAR_TRAIT_COMBINATIONS, type CalendarSyncFixture, calendarSyncContract } from "./sync-contract.js";
+export { type FakeCalendarWriter, type FakeCalendarWriterCall, fakeCalendarWriter } from "./writer.js";
+export { type CalendarWriterFixture, calendarWriterContract } from "./writer-contract.js";

package/dist/calendar/testing/index.js

@@ -3,3 +3,5 @@ export { memoryEventStore } from "./memory.js";
 export { fakeCalendarSource } from "./source.js";
 export { calendarSourceContract } from "./source-contract.js";
 export { CALENDAR_TRAIT_COMBINATIONS, calendarSyncContract } from "./sync-contract.js";
+export { fakeCalendarWriter } from "./writer.js";
+export { calendarWriterContract } from "./writer-contract.js";

package/dist/calendar/testing/memory.js

@@ -235,6 +235,7 @@ export const memoryEventStore = () => {
             joinKey: joinUrl ? (joinKeyOf(joinUrl) ?? "") : null,
             url: input.url ?? null,
             externalUpdatedAt: input.externalUpdatedAt ?? null,
+            etag: input.etag ?? null,
             seenAt: now,
             deletedAt: null,
             updatedAt: now,
@@ -386,6 +387,10 @@ export const memoryEventStore = () => {
                     refreshEvent(eventId, now);
             return marked.length;
         },
+        async entry(calendarId, externalId) {
+            const found = entries.find((one) => one.calendarId === calendarId && one.externalId === externalId);
+            return found ? stored(found) : null;
+        },
         async cursor(calendarId) {
             return cursors.get(calendarId) ?? null;
         },

package/dist/calendar/testing/writer-contract.d.ts

@@ -0,0 +1,23 @@
+import type { ContractCase, EntryInput, StoredCalendar } from "../../meetings/index.js";
+import type { CalendarWriter } from "../writer.js";
+/** One writer over recorded or held responses, fresh for each case. */
+export interface CalendarWriterFixture {
+    writer: CalendarWriter;
+    calendar: StoredCalendar;
+    /** A single event the provider holds, with its current `etag`. */
+    existing: EntryInput;
+    /** Another client changes `existing`, so its `etag` is old. */
+    changeBehind: () => void | Promise<void>;
+    /** The next write takes effect, and its answer is lost: the writer throws `outcome_unknown`. */
+    loseNextAnswer: () => void;
+    /** Whether each write so far asked the provider to mail the attendees, in order. */
+    notified: () => boolean[];
+    /** A time the provider accepts for a new event; the contract creates one-hour events from it. */
+    at: number;
+}
+/**
+ * What every calendar writer keeps (gcal-cli plan §9, W1): a stale `etag` is a conflict, never an overwrite; a create
+ * retried with its id finds the event; `notify: false` mails nobody, and a profile that keeps `events.notify` at its
+ * default never reaches the provider with a write that would.
+ */
+export declare const calendarWriterContract: (fixture: () => CalendarWriterFixture | Promise<CalendarWriterFixture>) => ContractCase[];

package/dist/calendar/testing/writer-contract.js

@@ -0,0 +1,137 @@
+import assert from "node:assert/strict";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { isCliError } from "@wirecat/cli-base";
+import { createEvent } from "../writes.js";
+import { memoryEventStore } from "./memory.js";
+const reasonOf = (error) => (isCliError(error) ? error.details.reason : undefined);
+const rejectsWith = async (promise, check, message) => {
+    try {
+        await promise;
+    }
+    catch (error) {
+        assert.ok(check(error), `${message}, got ${String(error)}`);
+        return;
+    }
+    assert.fail(`${message}, but it succeeded`);
+};
+const ID = "contract0sample0id0001";
+/**
+ * What every calendar writer keeps (gcal-cli plan §9, W1): a stale `etag` is a conflict, never an overwrite; a create
+ * retried with its id finds the event; `notify: false` mails nobody, and a profile that keeps `events.notify` at its
+ * default never reaches the provider with a write that would.
+ */
+export const calendarWriterContract = (fixture) => {
+    const draft = (at, extra = {}) => ({
+        title: "Example planning",
+        startsAt: at,
+        endsAt: at + 3_600_000,
+        timezone: "UTC",
+        ...extra,
+    });
+    const cases = [
+        {
+            name: "a create returns the event with its etag",
+            run: async () => {
+                const f = await fixture();
+                const made = await f.writer.create(f.calendar, draft(f.at), { id: ID, notify: false });
+                assert.equal(made.title, "Example planning");
+                assert.equal(made.status, "confirmed");
+                assert.equal(typeof made.etag, "string");
+            },
+        },
+        {
+            name: "a create retried with the same id after a lost answer finds the event instead of making another",
+            run: async () => {
+                const f = await fixture();
+                f.loseNextAnswer();
+                await rejectsWith(f.writer.create(f.calendar, draft(f.at), { id: ID, notify: false }), (error) => isCliError(error) && error.code === "outcome_unknown", "a lost answer is outcome_unknown");
+                const retried = await f.writer.create(f.calendar, draft(f.at), { id: ID, notify: false });
+                const again = await f.writer.create(f.calendar, draft(f.at), { id: ID, notify: false });
+                assert.equal(again.externalId, retried.externalId);
+            },
+        },
+        {
+            name: "a change with the current etag returns a new one",
+            run: async () => {
+                const f = await fixture();
+                const changed = await f.writer.update(f.calendar, f.existing.externalId, { title: "Example planning (moved)" }, { scope: "this", etag: f.existing.etag, notify: false });
+                assert.equal(changed.title, "Example planning (moved)");
+                assert.notEqual(changed.etag, f.existing.etag);
+            },
+        },
+        ...["update", "remove", "respond"].map((write) => ({
+            name: `${write} with an old etag is a conflict, never an overwrite`,
+            run: async () => {
+                const f = await fixture();
+                await f.changeBehind();
+                const options = { scope: "this", etag: f.existing.etag, notify: false };
+                const id = f.existing.externalId;
+                await rejectsWith(write === "update"
+                    ? f.writer.update(f.calendar, id, { title: "Overwritten" }, options)
+                    : write === "remove"
+                        ? f.writer.remove(f.calendar, id, options)
+                        : f.writer.respond(f.calendar, id, "declined", options), (error) => reasonOf(error) === "event.conflict", "a stale etag is a calendarConflict()");
+            },
+        })),
+        {
+            name: "notify reaches the provider as given: false mails nobody",
+            run: async () => {
+                const f = await fixture();
+                const before = f.notified().length;
+                await f.writer.create(f.calendar, draft(f.at, { attendees: [{ email: "ana@example.com" }] }), {
+                    id: ID,
+                    notify: false,
+                });
+                await f.writer.respond(f.calendar, f.existing.externalId, "accepted", {
+                    etag: f.existing.etag,
+                    notify: true,
+                });
+                assert.deepEqual(f.notified().slice(before), [false, true]);
+            },
+        },
+        {
+            name: "with events.notify at its default, a create that would mail attendees is refused before the provider",
+            run: async () => {
+                const f = await fixture();
+                const store = memoryEventStore();
+                const [calendar] = await store.saveCalendars(1, [{ ...f.calendar, syncByDefault: true }], f.at);
+                const home = mkdtempSync(join(tmpdir(), "calendar-writer-contract-"));
+                const before = f.notified().length;
+                await rejectsWith(createEvent({
+                    store,
+                    accountId: 1,
+                    writes: {
+                        writer: f.writer,
+                        app: {
+                            command: "example",
+                            appName: "example-cli",
+                            envPrefix: "EXAMPLE",
+                            description: "",
+                            version: "0",
+                        },
+                        settings: () => ({
+                            profile: "work",
+                            permissions: { events: "allow" },
+                            permissionSources: {},
+                            sendsPerHour: 30,
+                        }),
+                        env: { HOME: home, XDG_DATA_HOME: home, EXAMPLE_STATE_DIR: home },
+                    },
+                    ask: async () => { },
+                    now: f.at,
+                    zone: "UTC",
+                    names: { notify: "notify", id: "id", calendar: "calendar", series: "series" },
+                }, String(calendar?.id), {
+                    title: "Example planning",
+                    startTime: new Date(f.at).toISOString(),
+                    endTime: new Date(f.at + 3_600_000).toISOString(),
+                    attendees: ["ana@example.com"],
+                }, { notify: true }), (error) => isCliError(error) && error.code === "permission_error", "events.notify is deny by default");
+                assert.equal(f.notified().length, before, "the provider was not called");
+            },
+        },
+    ];
+    return cases;
+};

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

@@ -0,0 +1,26 @@
+import type { EntryInput } from "../../meetings/index.js";
+import { type CalendarWriter } from "../writer.js";
+export interface FakeCalendarWriterCall {
+    write: "create" | "update" | "remove" | "respond";
+    calendar: string;
+    externalId: string;
+    notify: boolean;
+    scope?: "this" | "series";
+}
+/**
+ * A provider's calendars held in memory, as a writer sees them. Every entry carries an etag that each change moves
+ * on; a write with an older one is a conflict, as Google's or CalDAV's `If-Match` is.
+ */
+export interface FakeCalendarWriter extends CalendarWriter {
+    /** Entries the provider holds already, as a sync would have stored them; each gets an etag unless it has one. */
+    put(calendar: string, ...entries: EntryInput[]): EntryInput[];
+    /** Another client changes the entry: its etag moves on, so the stored one is old. */
+    changeBehind(calendar: string, externalId: string): void;
+    /** The next write takes effect, and then its answer is lost: it throws `outcome_unknown`. */
+    loseNextAnswer(): void;
+    held(calendar: string): EntryInput[];
+    readonly calls: FakeCalendarWriterCall[];
+}
+export declare const fakeCalendarWriter: (options?: {
+    provider?: string;
+}) => FakeCalendarWriter;

package/dist/calendar/testing/writer.js

@@ -0,0 +1,101 @@
+import { CliError } from "@wirecat/cli-base";
+import { calendarConflict } from "../writer.js";
+export const fakeCalendarWriter = (options = {}) => {
+    const calendars = new Map();
+    const calls = [];
+    let version = 0;
+    let lose = false;
+    const of = (calendar) => {
+        if (!calendars.has(calendar))
+            calendars.set(calendar, new Map());
+        return calendars.get(calendar);
+    };
+    const stamp = (entry) => ({ ...entry, etag: `"v${++version}"` });
+    const answer = (value) => {
+        if (!lose)
+            return value;
+        lose = false;
+        throw new CliError("outcome_unknown", "the provider did not answer");
+    };
+    const current = (calendar, externalId, etag) => {
+        const found = of(calendar.externalId).get(externalId);
+        if (!found || found.status === "cancelled")
+            throw new CliError("not_found", `no event ${externalId}`);
+        if (found.etag !== etag)
+            throw calendarConflict();
+        return found;
+    };
+    const fields = (patch) => {
+        const { attendees, title, ...rest } = patch;
+        return {
+            ...rest,
+            ...(title === undefined ? {} : { title }),
+            ...(patch.startDate === undefined ? {} : { allDay: true, startsAt: null, endsAt: null }),
+            ...(patch.startsAt === undefined ? {} : { allDay: false, startDate: null, endDate: null }),
+            ...(attendees === undefined
+                ? {}
+                : { participants: attendees.map(({ email, optional }) => ({ email, optional: optional === true })) }),
+        };
+    };
+    return {
+        provider: options.provider ?? "example-calendar",
+        calls,
+        put(calendar, ...entries) {
+            return entries.map((entry) => {
+                const held = entry.etag ? entry : stamp(entry);
+                of(calendar).set(entry.externalId, held);
+                return held;
+            });
+        },
+        changeBehind(calendar, externalId) {
+            const found = of(calendar).get(externalId);
+            if (found)
+                of(calendar).set(externalId, stamp(found));
+        },
+        loseNextAnswer() {
+            lose = true;
+        },
+        held(calendar) {
+            return [...of(calendar).values()];
+        },
+        async create(calendar, draft, { id, notify }) {
+            calls.push({ write: "create", calendar: calendar.externalId, externalId: id, notify });
+            const existing = of(calendar.externalId).get(id);
+            if (existing)
+                return answer(existing);
+            const entry = stamp({
+                externalId: id,
+                kind: "single",
+                status: "confirmed",
+                participants: [],
+                ...fields(draft),
+            });
+            of(calendar.externalId).set(id, entry);
+            return answer(entry);
+        },
+        async update(calendar, externalId, patch, { scope, etag, notify }) {
+            calls.push({ write: "update", calendar: calendar.externalId, externalId, notify, scope });
+            const entry = stamp({ ...current(calendar, externalId, etag), ...fields(patch) });
+            of(calendar.externalId).set(externalId, entry);
+            return answer(entry);
+        },
+        async remove(calendar, externalId, { scope, etag, notify }) {
+            calls.push({ write: "remove", calendar: calendar.externalId, externalId, notify, scope });
+            of(calendar.externalId).set(externalId, stamp({ ...current(calendar, externalId, etag), status: "cancelled" }));
+            answer(undefined);
+        },
+        async respond(calendar, externalId, response, { etag, notify }) {
+            calls.push({ write: "respond", calendar: calendar.externalId, externalId, notify });
+            const found = current(calendar, externalId, etag);
+            const entry = stamp({
+                ...found,
+                ownResponse: response,
+                ...(found.participants
+                    ? { participants: found.participants.map((one) => (one.self ? { ...one, response } : one)) }
+                    : {}),
+            });
+            of(calendar.externalId).set(externalId, entry);
+            return answer(entry);
+        },
+    };
+};