circal-mcp 0.4.0 → 0.5.0

package/README.md

@@ -46,16 +46,25 @@ zone, revision) plus a ready-to-paste config block. Paste that block into
 your client below, swap the path if it picked up the wrong file, then
 restart the client.
 
-> **Use `circal-mcp@0.3.0` or newer** (`npx -y circal-mcp` resolves it).
-> The cautionary tale behind that floor: `0.1.0` predated nine fields in
-> `src/lib` (`free`, `remindLead`, `organizer` and the guest pair on an
-> event; `backupNudge`, `backupInterval`, `deviceZone`, `stampedZones` in
-> settings), and every write round-trips the whole document through its
-> reader, so it silently dropped all nine — measured, same fixture, two
-> bundles. A current server refuses to write a document whose format is
-> newer than its own, so a stale bundle can no longer damage one unnoticed;
-> it will simply refuse. Contributors run against their own build with
-> `pnpm build:mcp` → `node mcp/dist/circal-mcp.mjs`.
+> **Use `circal-mcp@0.5.0` or newer** (`npx -y circal-mcp` resolves it).
+> The cautionary tale behind that floor: `0.1.0` predated ten fields in
+> `src/lib` (`free`, `travel`, `remindLead`, `organizer` and the guest pair
+> on an event; `backupNudge`, `backupInterval`, `deviceZone`, `stampedZones`
+> in settings), and every write round-trips the whole document through its
+> reader, so it silently dropped all ten — measured, same fixture, two
+> bundles.
+>
+> **The version gate does not save you from this, and the floor is why.** It
+> refuses a document whose _envelope_ is newer than the server's, and an
+> envelope version is bumped only when a whole key changes meaning — the
+> `tasks` list going missing was one. A new field on an event is not: `travel`
+> shipped at `MIRROR_VERSION` 3 like `free` before it, so a `0.4.1` bundle
+> reads `3 <= 3`, writes happily, and erases the field from every event in the
+> file. The gates stop only what they can see coming (`src/lib/mirror.ts`).
+> Reads are always safe; it is writes that lose data. So: **republish and
+> reinstall the server whenever a `CalEvent` or `Settings` field lands**, and
+> raise this floor in the same commit. Contributors run against their own
+> build with `pnpm build:mcp` → `node mcp/dist/circal-mcp.mjs`.
 
 ### Claude Desktop
 

package/dist/circal-mcp.mjs

@@ -2217,6 +2217,12 @@ function readRemindLead(value) {
   if (value < 0 || value > REMIND_LEAD_MAX) return REMIND_INHERIT;
   return value;
 }
+var TRAVEL_MAX = MINUTES_PER_DAY;
+function readTravel(value) {
+  if (typeof value !== "number" || !Number.isInteger(value)) return 0;
+  if (value < 0 || value > TRAVEL_MAX) return 0;
+  return value;
+}
 var PARTSTATS = ["needs-action", "accepted", "declined", "tentative"];
 var ATTENDEE_MAX = 32;
 var GUEST_NAME_MAX = 64;
@@ -2279,6 +2285,10 @@ function readGraves(value) {
   }
   return [...latest].map(([id, at]) => ({ id, at })).sort((a, b) => b.at - a.at).slice(0, GRAVE_MAX);
 }
+function travelMinutes(occ) {
+  if (occ.task) return 0;
+  return Math.min(occ.event.travel, occ.startMin);
+}
 function overridesIn(events) {
   const out = /* @__PURE__ */ new Map();
   for (const event of events) {
@@ -2347,7 +2357,9 @@ function packLanes(occurrences, pad2 = 6) {
   return occurrences.map((occ) => {
     if (occ.event.allDay) return occ;
     if (occ.task && occ.startMin === occ.endMin) return occ;
-    let lane = laneEnds.findIndex((end) => end <= occ.startMin + pad2);
+    const travel = travelMinutes(occ);
+    const from = occ.startMin - travel;
+    let lane = laneEnds.findIndex((end) => end <= from + (travel > 0 ? 0 : pad2));
     if (lane === -1) lane = laneEnds.length;
     laneEnds[lane] = occ.endMin;
     return { ...occ, lane };
@@ -2378,6 +2390,8 @@ function taskEvent(task, start, end) {
     color: task.color,
     icon: task.icon,
     free: false,
+    // You do not commute to a deadline, and a plan is the work itself.
+    travel: 0,
     remindLead: REMIND_INHERIT,
     organizer: null,
     attendees: [],
@@ -2441,8 +2455,13 @@ function taskOccurrences(tasks, calendars, day) {
   return out;
 }
 var DEFAULT_WAKING = { from: 8 * 60, to: 22 * 60 };
+function bookedBlock(occ) {
+  if (occ.event.allDay || occ.event.free) return null;
+  const start = occ.startMin - travelMinutes(occ);
+  return occ.endMin > start ? { start, end: occ.endMin } : null;
+}
 function freeGaps(occurrences, minMinutes, from, to) {
-  const busy = occurrences.filter((o) => !o.event.allDay && !o.event.free).map((o) => ({ start: Math.max(o.startMin, from), end: Math.min(o.endMin, to) })).filter((b) => b.end > b.start).sort((a, b) => a.start - b.start);
+  const busy = occurrences.map(bookedBlock).filter((block) => block !== null).map((block) => ({ start: Math.max(block.start, from), end: Math.min(block.end, to) })).filter((b) => b.end > b.start).sort((a, b) => a.start - b.start);
   const gaps = [];
   let cursor = from;
   for (const block of busy) {
@@ -3561,6 +3580,9 @@ function draftEvent(day, startMin, endMin, calendarId, repeat = "never") {
     icon: "",
     // Busy: a gesture that named a time meant that time to be spoken for.
     free: false,
+    // None: a drag named when to be somewhere, never how long getting there
+    // takes. Travel is typed, so a gesture cannot have meant one.
+    travel: 0,
     // Inheriting, which is the only answer a gesture gives: the drag named a
     // time, not how much warning it wants about it.
     remindLead: REMIND_INHERIT,
@@ -3745,6 +3767,10 @@ function readEvent(value) {
     // exported before this field existed was. A truthy string in a
     // hand-edited blob must not quietly take a meeting off the day's total.
     free: value.free === true,
+    // What a legal travel is lives in `events.ts`, beside the clipping and the
+    // ceiling it shares bounds with: a hand-edited blob's `-5` or `"20"` comes
+    // back `0`, which is what an event exported before this field existed was.
+    travel: readTravel(value.travel),
     // What a legal lead is lives in `remind.ts`, beside the three states it
     // has to distinguish: an unreadable one comes back inheriting, which is
     // what an event exported before this field existed already did.
@@ -4890,6 +4916,9 @@ function buildEventRecord(input, calendars, settings, pin) {
     // Busy. There is no tool argument for this yet, and an agent asked to put
     // an hour in the diary means the hour to be spoken for.
     free: false,
+    // No run-up unless the caller named one — an invented commute would be an
+    // agent deciding when its user has to leave the house.
+    travel: input.travel !== void 0 ? readTravel(input.travel) : 0,
     // Inheriting unless the caller named a lead of its own — an event created
     // with one it was not asked for would be an agent quietly deciding how
     // much warning its user wants.
@@ -4932,6 +4961,10 @@ function applyPatchToEvent(base, input, calendars, settings, anchorMs = base.sta
     // to busy — so leaving it out would quietly rebook a free event the
     // moment its title was edited.
     free: base.free,
+    // Carried for `free`'s reason, one field over: `readEvent` defaults an
+    // absent travel to none, so leaving it out would erase a commute the
+    // moment an assistant fixed a typo in the title.
+    travel: input.travel !== void 0 ? readTravel(input.travel) : base.travel,
     // Carried unless the patch names one — `readEvent` reads an absent lead
     // as inheriting, so leaving it out would un-silence an event the user
     // silenced the moment an assistant fixed a typo in its title.
@@ -5182,7 +5215,13 @@ function performQuickAdd(contents, text, date, pin) {
   };
 }
 var KEYED_ID_PREFIX = "x-";
+var UPSERT_KEY_RE = /^[A-Za-z0-9._:-]{1,64}$/;
 function keyedId(key) {
+  if (!UPSERT_KEY_RE.test(key)) {
+    throw new RefusalError(
+      `"key" must be 1-64 characters of letters, digits and . _ : - \u2014 it becomes the record's id`
+    );
+  }
   return `${KEYED_ID_PREFIX}${key}`;
 }
 function performCreateEvent(contents, input, key, pin) {
@@ -5563,14 +5602,17 @@ function eventFieldsShape() {
     zone: z.string().describe(
       `IANA zone the date and times are written in, e.g. "Asia/Seoul" \u2014 for a deadline abroad. Stored on the event so every surface prints both clocks; timed events only. On update, "" clears it back to floating (local) time, and patched times are read on the event's own zone.`
     ).optional(),
+    travel: z.number().int().min(0).max(TRAVEL_MAX).describe(
+      `Minutes of travel before the start, drawn as a run-up ahead of the event and booked as time spent, so nothing else is offered that window. 0 = none (the default), up to ${TRAVEL_MAX}.`
+    ).optional(),
     remindLead: z.union([z.number().int().min(0).max(REMIND_LEAD_MAX), z.enum(["inherit", "silent"])]).describe(
       'Reminder lead: minutes before the start (0 = as it starts), "silent" (never fires), or "inherit" (follow the calendar, then the setting \u2014 the default).'
     ).optional(),
     recurrence: recurrenceSchema.optional()
   };
 }
-var upsertKeySchema = z.string().regex(/^[A-Za-z0-9._:-]{1,64}$/, "letters, digits, . _ : -, up to 64").describe(
-  "Caller-chosen external key for idempotent upsert: the same key always names the same event, so re-running a mirror updates in place instead of duplicating. Omitted, every call creates a fresh event."
+var upsertKeySchema = z.string().regex(UPSERT_KEY_RE, "letters, digits, . _ : -, up to 64").describe(
+  "Caller-chosen external key for idempotent upsert: the same key always names the same event, so re-running a mirror updates in place instead of duplicating. A keyed create also overrides a prior deletion \u2014 the source of truth re-asserts \u2014 so to drop a record for good, remove it from the source, not just the calendar. Omitted, every call creates a fresh event."
 );
 var createEventFieldsSchema = z.strictObject({
   ...eventFieldsShape(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "circal-mcp",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "type": "module",
   "description": "MCP server for circal — read and write your calendar through its mirror file or its encrypted cloud copy",
   "license": "AGPL-3.0-only",