@wirecat/cli-core 0.457.0 → 0.458.0

package/CHANGELOG.md

@@ -7,6 +7,42 @@ shape of this file.
 
 ## Unreleased
 
+## 0.458.0 — 27.10.2026
+
+### Added
+
+- **Calendar writes (`@wirecat/cli-core/calendar`).** An optional `CalendarWriter` beside `CalendarSource`:
+  `create(calendar, draft, { id, notify })`, `update(calendar, externalId, patch, { scope, etag, notify })`,
+  `remove(calendar, externalId, { scope, etag, notify })` and `respond(calendar, externalId, response, { etag,
+  notify })`, in neutral words (`EventDraft`, `EventPatch`, `WriteScope` `this | series`, `EventResponse`). The id of a
+  create is chosen before the call and journaled as its `sendId`, so a retry after `outcome_unknown` with the same id
+  finds the event instead of making a second one. Every change sends the stored `etag`; an adapter turns a mismatch
+  into `calendarConflict()` (`validation_error`, reason `event.conflict`: sync and try again), never an overwrite. What
+  a write returns is saved at once; a deletion cancels the entry as a sync would. Repeating events are not created
+  here, and "this and following" is not offered.
+- **`events create | update | delete | respond`** in `addCalendarCommands`, only when the CLI passes
+  `writes: CalendarWrites` (the writer, `app`, the profile's `GuardSettings`, and `extraKeys(write)` for keys the
+  CLI adds, such as gcal's `api.calendar.events.insert`). Each goes through `guardFor` and the send journal as a
+  messenger's writes do (WC-PERM-13, WC-PERM-17), and `--dry-run` previews it. Built-in levels
+  (`CALENDAR_WRITE_DEFAULTS`, WC-PERM-6/7): `events.create`, `events.update`, `events.respond` and `events.delete`
+  `ask`; `events.delete.series` `deny`; `events.notify` `deny`. Times are `--start-time`/`--end-time`, an all-day
+  event `--start-date`/`--end-date` (the last day). `--notify` or `--no-notify` is required when the event has
+  attendees other than the owner (reason `event.notify-required`), and `--notify` must pass `events.notify`.
+  `CALENDAR_WRITE_KEYS` lists the keys that are not command paths, for `commandPermissions({ extra })`.
+  `addCalendarCommands` now honours a global `--dry-run` in any host program, as cli-core's other shared commands do.
+- **`calendarWriteTools`** (`event_create`, `event_update`, `event_delete`, `event_respond`) for `callCalendarTool`
+  with `writes: (accountId) => CalendarWrites`. Over MCP `ask` goes ahead (WC-MCP-7); `deny`, `readonly`,
+  `events.notify` and the extra keys still refuse; `notify` is `true` or `false`. A write acts in the account named, or the only one that holds the
+  calendar or event; two make it ask for `account_id`.
+- **Contract kit:** `fakeCalendarWriter` and `calendarWriterContract` (a stale etag is a conflict for update, remove
+  and respond; a create retried with its id finds the event; `notify` reaches the provider as given; with
+  `events.notify` at its default a create that would mail attendees never reaches the provider).
+
+### Changed — may break callers
+
+- **`EventStore` has `entry(calendarId, externalId)`, and `StoredEntry` has `etag`.** A store of its own must add
+  both; the column already exists, so there is no migration.
+
 ## 0.457.0 — 27.10.2026
 
 ### Fixed

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

@@ -2,6 +2,7 @@ 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";
+import { type CalendarWrites } from "../writes.js";
 export interface CalendarCommandDeps {
     store: EventStore;
     /** The selected profile's calendar account: every command reads and syncs only it. */
@@ -20,5 +21,7 @@ export interface CalendarCommandDeps {
     now?: () => number;
     /** The zone `today`, `week` and a bare date are read in; the computer's when absent. */
     timezone?: string;
+    /** The provider's writer and the profile's guard: `events create|update|delete|respond` exist only with it. */
+    writes?: CalendarWrites;
 }
 export declare const addCalendarCommands: (program: Command, deps: CalendarCommandDeps) => void;

package/dist/calendar/cli/index.js

@@ -1,14 +1,18 @@
 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 { Argument, InvalidArgumentError } from "commander";
+import { honoursDryRun } from "../../cli/dry-run-guard.js";
+import { terminalAsker } from "../../cli/messenger/ask.js";
 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";
+import { createEvent, deleteEvent, EVENT_RESPONSES, respondToEvent, updateEvent, } from "../writes.js";
 const LOCAL_READ = { remote: "none", local: "read" };
 const LOCAL_WRITE = { remote: "none", local: "write" };
 const FETCH = { remote: "read", local: "write" };
+const REMOTE_WRITE = { remote: "write", local: "write" };
 const GROUP = { remote: "none", local: "none" };
 /** How many pieces one `sync --embed` embeds, as drive's. */
 const EMBED_MAX = 600;
@@ -132,6 +136,8 @@ const addCalendarCommandsDefinition = (program, deps) => {
             ...(opts.newest ? { newest: true } : {}),
         }), command);
     });
+    if (deps.writes)
+        addEventWrites(events, deps.writes, { deps, now, zone, output, print, example });
     const people = annotate(program.command("people").description("the people in the account's events"), {
         effects: GROUP,
     });
@@ -172,4 +178,69 @@ const addCalendarCommandsDefinition = (program, deps) => {
         print(await resolveAnswer(deps.store, review, choice, now()), command);
     });
 };
-export const addCalendarCommands = sharedCommand(addCalendarCommandsDefinition);
+const collect = (value, previous = []) => [...previous, value];
+const addEventWrites = (events, writes, { deps, now, zone, output, print, example }) => {
+    const context = (command) => ({
+        store: deps.store,
+        accountId: deps.accountId,
+        writes,
+        ask: terminalAsker(command),
+        now: now(),
+        zone: zone(),
+        names: { notify: "--notify or --no-notify", id: "--id", calendar: "--calendar", series: "--series" },
+    });
+    // Left out on purpose: with other attendees the owner must choose, so neither switch is the default.
+    const notify = (command) => command
+        .option("--notify", "the provider mails the other attendees; needs events.notify allowed")
+        .option("--no-notify", "the provider mails nobody; one of the two is required when there are other attendees");
+    const fields = (command, replacing) => command
+        .option("--title <title>", "the event's title")
+        .option("--start-time <time>", "when it starts: a time in your zone, or one with its own")
+        .option("--end-time <time>", "when it ends")
+        .option("--start-date <date>", "the first day of an all-day event, YYYY-MM-DD")
+        .option("--end-date <date>", "the last day of an all-day event")
+        .option("--location <text>", "where; empty clears it")
+        .option("--description <text>", "the details; empty clears it")
+        .option("--attendee <email>", `an attendee; repeat for each${replacing ? ", replacing the list" : ""}`, collect);
+    const fieldsOf = ({ attendee, ...given }) => ({
+        ...Object.fromEntries(Object.entries(given).filter(([, value]) => value !== undefined)),
+        ...(attendee === undefined ? {} : { attendees: attendee }),
+    });
+    const choicesOf = ({ calendar, series, notify }) => ({
+        ...(calendar === undefined ? {} : { calendar }),
+        ...(series ? { series: true } : {}),
+        ...(notify === undefined ? {} : { notify }),
+    });
+    const write = (name) => annotate(events.command(name), { effects: REMOTE_WRITE, offline: false });
+    const target = (command) => command
+        .argument("<event>", "the event's id, or event:<id>")
+        .option("--calendar <id>", "the calendar, when the event is on more than one of the account's");
+    output(example(notify(fields(write("create"), false)
+        .description("add an event to a calendar; one that repeats is made in the calendar itself")
+        .argument("<calendar>", "the calendar's id, or the provider's id")).option("--id <id>", "the id a create that ended in outcome_unknown named: a retry finds that event"), "events create 3 --title 'Example planning' --start-time 2026-11-02T10:00 --end-time 2026-11-02T11:00", "events create 3 --title 'Example review' --start-date 2026-11-03 --end-date 2026-11-03 " +
+        "--attendee ana@example.com --no-notify")).action(async (calendar, opts, command) => {
+        const { notify: choice, id, ...rest } = opts;
+        print(await createEvent(context(command), calendar, fieldsOf(rest), {
+            ...(choice === undefined ? {} : { notify: choice }),
+            ...(id === undefined ? {} : { id }),
+        }), command);
+    });
+    output(example(notify(target(fields(write("update"), true))
+        .description("change an event; with --series every occurrence of the repeating event")
+        .option("--series", "change the whole repeating event, not only this occurrence")), "events update event:42 --start-time 2026-11-02T14:00 --end-time 2026-11-02T15:00 --notify")).action(async (reference, opts, command) => {
+        const { calendar: _calendar, series: _series, notify: _notify, ...rest } = opts;
+        print(await updateEvent(context(command), reference, fieldsOf(rest), choicesOf(opts)), command);
+    });
+    output(example(notify(target(write("delete"))
+        .description("delete an event; a whole repeating event needs events.delete.series allowed first")
+        .option("--series", "delete the whole repeating event, not only this occurrence")), "events delete event:42 --no-notify")).action(async (reference, opts, command) => {
+        print(await deleteEvent(context(command), reference, choicesOf(opts)), command);
+    });
+    output(example(notify(target(write("respond"))
+        .description("answer an invitation; the organiser is told only with --notify")
+        .addArgument(new Argument("<response>", "the answer").choices(EVENT_RESPONSES))), "events respond event:42 accepted --notify")).action(async (reference, response, opts, command) => {
+        print(await respondToEvent(context(command), reference, response, choicesOf(opts)), command);
+    });
+};
+// honoursDryRun: a host program other than `run` would otherwise let a write through under --dry-run.
+export const addCalendarCommands = honoursDryRun(sharedCommand(addCalendarCommandsDefinition));

package/dist/calendar/index.d.ts

@@ -1,3 +1,5 @@
 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";
+export { CALENDAR_WRITE_DEFAULTS, CALENDAR_WRITE_KEYS, type CalendarWrite, type CalendarWriter, calendarConflict, EVENTS_DELETE_SERIES_KEY, EVENTS_NOTIFY_KEY, type EventDraft, type EventPatch, type EventResponse, type WriteScope, } from "./writer.js";
+export type { CalendarWrites } from "./writes.js";

package/dist/calendar/index.js

@@ -1 +1,2 @@
 export { calendarSyncWindow, parseCalendarCursor, syncCalendars, } from "./sync.js";
+export { CALENDAR_WRITE_DEFAULTS, CALENDAR_WRITE_KEYS, calendarConflict, EVENTS_DELETE_SERIES_KEY, EVENTS_NOTIFY_KEY, } from "./writer.js";