plugins/caldav
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

one CRUD, three callers — the browser and the agent stop writing iCalendar

Browse Source 
the skill told an agent how to hand-write a .ics: escape the commas, fold at 75
octets, CRLF, DTSTAMP is required, and DTEND is the day after. all true, all
silent when wrong, and the browser had learned the same lesson separately in its
own copy of the code. this makes the sidecar the only thing that knows the
format, and gives everyone else fields.

WHAT WAS MISSING BEFORE THE SKILL COULD CHANGE. reading was already JSON, and
create-event landed this morning. this adds PATCH /_officer/item — change some
fields of an event or a card — and POST /_officer/contact. delete already worked.
with those the skill has no reason left to mention iCalendar, so it does not.

PATCH IS READ-PATCH-PUT, SERVER SIDE. it reads the stored text, replaces only the
lines it owns, and puts the whole thing back, so alarms, attendees, RRULEs and
every X- property a phone invented survive an edit made from a form that cannot
show them. that logic came out of the browser, where it had needed a duplicate of
the escaping and folding rules to live; the agent would have been a third copy in
bash. the web bundle now contains no iCalendar literals at all.

AND LIVE TESTING FOUND THE BUG THAT MATTERS. an event with a TZID is stored with
a VTIMEZONE block beside it, and that block has DTSTART lines of its own — the
rule for when summer time starts. taking the first DTSTART in the file rewrote
the TIMEZONE DEFINITION, left the event where it was, and answered ok. the
calendar showed the old time and the file was quietly corrupt. every write is now
confined to the first VEVENT or VCARD, and the file that caught it is a test.

three more traps handled rather than documented: a patch that reuses an all-day
event's stored DTEND must subtract the exclusive day first or the holiday drifts
every time the title is edited; moving a timed event must DROP a stale TZID
rather than preserve it, because a TZID and a Z together are a contradiction
clients resolve by moving the event; and a move bumps SEQUENCE, which is how a
phone tells an update from a duplicate.

contacts got the create form the calendar had, so both screens now do all four.
editing a card sends the other emails and phones back untouched — the form shows
the first of each, and sending only that would delete the rest.

47 tests across the writer and the patcher. verified live against a real event
carrying an alarm, an attendee, an RRULE and an X- property: all four intact
after a rename, a relocation and a move to a different day.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Officer-Session: 656f5c85-e49a-4f1f-b9f3-042a04b4d043
This commit is contained in:
pastilhas
2026-08-27 10:51:22 +00:00
co-authored by Claude Opus 5
parent 25c8502c4b
commit 43cb531dc2
10 changed files with 871 additions and 348 deletions
Download Patch File Download Diff File Expand all files Collapse all files
web/dav/CalendarView.tsx
+5 -6
View File
@@ -2,7 +2,7 @@ import type { CalendarEvent } from './shared';
import { useState } from 'react';
import { CalendarDays, MapPin, Repeat, Pencil, Trash2, Check, X, Plus } from 'lucide-react';
import { useCalendarEvents, useSelectedCollection } from './useDavData';
import { useDavEdit, setProperty, CREATING, type NewEvent } from './useDavEdit';
import { useDavEdit, CREATING, type NewEvent } from './useDavEdit';
import { useTranslation } from 'officerdev';
// Right panel of /calendar. Deliberately a grouped agenda list, not a month grid: the sidecar returns
@@ -101,7 +101,7 @@ export const CalendarView = () => {
const submitNew = (e: React.FormEvent) => {
e.preventDefault();
if (!draftNew?.summary.trim()) return;
void edit.create(selected.path, toEvent(draftNew)).then((ok) => ok && setDraftNew(null));
void edit.createEvent(selected.path, toEvent(draftNew)).then((ok) => ok && setDraftNew(null));
};
return (
@@ -230,11 +230,10 @@ export const CalendarView = () => {
onSubmit={(e) => {
e.preventDefault();
if (!ev.href) return;
// `null` removes the line; an empty string would leave an empty LOCATION behind.
void edit
.save(ev.href, (raw) =>
setProperty(setProperty(raw, 'SUMMARY', draft.summary), 'LOCATION', draft.location || null),
)
.then(() => setEditing(null));
.save(ev.href, { summary: draft.summary, location: draft.location || null })
.then((ok) => ok && setEditing(null));
}}
>
<input
web/dav/ContactsView.tsx
+107 -15
View File
@@ -1,7 +1,7 @@
import { useState } from 'react';
import { Building2, Mail, Phone, User, Pencil, Trash2, Check, X } from 'lucide-react';
import { Building2, Mail, Phone, User, Pencil, Trash2, Check, X, Plus } from 'lucide-react';
import { useDavContacts, useSelectedCollection } from './useDavData';
import { useDavEdit, setProperty } from './useDavEdit';
import { useDavEdit, CREATING } from './useDavEdit';
import { useTranslation } from 'officerdev';
// Right panel of /contacts: the selected address book as cards, sorted by name.
@@ -18,6 +18,10 @@ const initials = (name: string) =>
.map((part) => part[0]?.toUpperCase() ?? '')
.join('') || '?';
const FIELD = 'rounded-md border bg-background px-2 py-1 text-sm';
const blankDraft = () => ({ fullName: '', email: '', phone: '' });
export const ContactsView = () => {
const { t } = useTranslation();
const { selected, isLoading: loadingCollections } = useSelectedCollection('addressbook');
@@ -26,19 +30,104 @@ export const ContactsView = () => {
const [editing, setEditing] = useState<string | null>(null);
const [draft, setDraft] = useState({ fullName: '', email: '', phone: '' });
const [confirming, setConfirming] = useState<string | null>(null);
const [draftNew, setDraftNew] = useState<ReturnType<typeof blankDraft> | null>(null);
if (loadingCollections) return <Placeholder text="Loading address books…" />;
if (!selected) return <Placeholder text="No address books yet. Create one from a CardDAV client." />;
if (error) return <Placeholder text={t('dav.readFailed', { name: selected.displayName, reason: String(error) })} />;
if (isLoading) return <Placeholder text="Loading contacts…" />;
if (contacts.length === 0) return <Placeholder text={`${selected.displayName} has no contacts.`} />;
// Not an early return: the header carries the only way to ADD a card, and an empty address book is
// exactly when somebody wants it.
const notice = error
? t('dav.readFailed', { name: selected.displayName, reason: String(error) })
: isLoading
? 'Loading contacts…'
: contacts.length === 0
? `${selected.displayName} has no contacts.`
: null;
const sorted = [...contacts].sort((a, b) => a.fullName.localeCompare(b.fullName));
const submitNew = (e: React.FormEvent) => {
e.preventDefault();
if (!draftNew?.fullName.trim()) return;
void edit
.createContact(selected.path, {
fullName: draftNew.fullName.trim(),
emails: [draftNew.email].filter(Boolean),
phones: [draftNew.phone].filter(Boolean),
})
.then((ok) => ok && setDraftNew(null));
};
return (
<div className="h-full overflow-y-auto">
<div className="mx-auto grid max-w-4xl grid-cols-1 gap-3 p-6 sm:grid-cols-2">
{sorted.map((contact) => (
<div className="flex h-full flex-col">
<header className="flex shrink-0 items-center justify-between gap-3 border-b px-6 py-3">
<div className="min-w-0">
<div className="truncate text-sm font-semibold leading-tight">{selected.displayName}</div>
<div className="text-xs text-muted-foreground">
{contacts.length} {contacts.length === 1 ? 'contact' : 'contacts'}
</div>
</div>
<button
onClick={() => setDraftNew((d) => (d ? null : blankDraft()))}
className="flex shrink-0 items-center gap-1.5 rounded-lg bg-primary/10 px-3 py-1.5 text-xs font-medium text-primary transition-colors hover:bg-primary/20"
>
<Plus className="h-3.5 w-3.5" />
New contact
</button>
</header>
<div className="flex-1 overflow-y-auto">
{/* Name, one email, one phone. A card can hold far more, and a CardDAV client can put it there —
this is the form for adding somebody from their business card, not for modelling a person. */}
{draftNew && (
<form onSubmit={submitNew} className="mx-auto flex max-w-4xl flex-col gap-3 px-6 pt-6">
<div className="flex flex-col gap-3 rounded-xl border bg-card p-4">
<input
autoFocus
value={draftNew.fullName}
onChange={(e) => setDraftNew({ ...draftNew, fullName: e.target.value })}
placeholder="Name"
className={FIELD}
/>
<div className="flex flex-wrap gap-2">
<input
value={draftNew.email}
onChange={(e) => setDraftNew({ ...draftNew, email: e.target.value })}
placeholder="Email"
className={`${FIELD} min-w-0 flex-1 text-xs`}
/>
<input
value={draftNew.phone}
onChange={(e) => setDraftNew({ ...draftNew, phone: e.target.value })}
placeholder="Phone"
className={`${FIELD} min-w-0 flex-1 text-xs tabular-nums`}
/>
</div>
<div className="flex items-center gap-2">
<button
type="submit"
disabled={edit.busy === CREATING || !draftNew.fullName.trim()}
className="flex items-center gap-1 rounded-md bg-primary/10 px-3 py-1.5 text-xs font-medium text-primary disabled:opacity-50"
>
<Check className="h-3 w-3" /> {edit.busy === CREATING ? 'Creating…' : 'Create'}
</button>
<button
type="button"
onClick={() => setDraftNew(null)}
className="rounded-md px-2 py-1.5 text-xs text-muted-foreground"
>
Cancel
</button>
{edit.error && <span className="text-xs text-destructive">{edit.error}</span>}
</div>
</div>
</form>
)}
{notice && <Placeholder text={notice} />}
<div className="mx-auto grid max-w-4xl grid-cols-1 gap-3 p-6 sm:grid-cols-2">
{sorted.map((contact) => (
<article key={contact.uid} className="flex gap-3 rounded-xl border bg-card p-3">
<div className="flex h-10 w-10 shrink-0 items-center justify-center rounded-full bg-sky-500/15 text-sm font-semibold text-sky-600">
{initials(contact.fullName)}
@@ -81,13 +170,15 @@ export const ContactsView = () => {
onSubmit={(e) => {
e.preventDefault();
if (!contact.href) return;
/* The form shows the FIRST email and phone; a card can hold several. Sending just
the one would delete the rest, so the others are carried through untouched. */
void edit
.save(contact.href, (raw) => {
let out = setProperty(raw, 'FN', draft.fullName);
out = setProperty(out, 'EMAIL', draft.email || null);
return setProperty(out, 'TEL', draft.phone || null);
.save(contact.href, {
fullName: draft.fullName,
emails: [draft.email, ...contact.emails.slice(1)].filter(Boolean),
phones: [draft.phone, ...contact.phones.slice(1)].filter(Boolean),
})
.then(() => setEditing(null));
.then((ok) => ok && setEditing(null));
}}
>
<input
@@ -172,8 +263,9 @@ export const ContactsView = () => {
)}
</div>
)}
</article>
))}
</article>
))}
</div>
</div>
</div>
);
web/dav/useDavEdit.test.ts
-83
View File
@@ -1,83 +0,0 @@
import { describe, expect, test } from 'bun:test';
import { setProperty } from './useDavEdit';
import { parseEvents } from '../../sidecar/ical';
// setProperty is the whole editing story: it decides what an edit keeps and what it destroys. These
// cover the two ways it can quietly destroy something — dropping a property's parameters, and leaving
// half of a folded value behind.
const ICS = [
'BEGIN:VCALENDAR',
'VERSION:2.0',
'BEGIN:VEVENT',
'UID:abc',
'DTSTAMP:20260827T100000Z',
'DTSTART;TZID=Europe/Lisbon:20260828T130000',
'DTEND;TZID=Europe/Lisbon:20260828T140000',
'SUMMARY:Before',
'RRULE:FREQ=WEEKLY',
'BEGIN:VALARM',
'ACTION:DISPLAY',
'TRIGGER:-PT15M',
'END:VALARM',
'END:VEVENT',
'END:VCALENDAR',
].join('\r\n');
describe('setProperty', () => {
test('changes only the line it owns', () => {
const out = setProperty(ICS, 'SUMMARY', 'After');
expect(out.split('\r\n').length).toBe(ICS.split('\r\n').length);
expect(out).toContain('SUMMARY:After');
expect(out).toContain('RRULE:FREQ=WEEKLY');
expect(out).toContain('BEGIN:VALARM');
});
test('keeps a property that carries parameters', () => {
const out = setProperty(ICS, 'DTSTART', '20260901T090000');
expect(out).toContain('DTSTART;TZID=Europe/Lisbon:20260901T090000');
});
test('appends after UID when the property is absent, so it lands in the right component', () => {
const out = setProperty(ICS, 'LOCATION', 'Ramiro');
const lines = out.split('\r\n');
expect(lines[lines.indexOf('UID:abc') + 1]).toBe('LOCATION:Ramiro');
});
test('null removes the property', () => {
expect(setProperty(ICS, 'RRULE', null)).not.toContain('RRULE');
});
test('escapes the TEXT separators', () => {
const out = setProperty(ICS, 'SUMMARY', 'a, b; c');
expect(out).toContain(String.raw`SUMMARY:a\, b\; c`);
expect(parseEvents(out)[0]!.summary).toBe('a, b; c');
});
// The regression. A folded property spans several lines; replacing only the first left the rest
// behind, and they folded onto the NEW value — so each edit silently inherited the tail of the last.
test('replaces the whole of a folded value, continuations included', () => {
const folded = ICS.replace('SUMMARY:Before', 'SUMMARY:Before, and then quite a lot more text that\r\n was folded onto a second line');
const out = setProperty(folded, 'SUMMARY', 'After');
expect(parseEvents(out)[0]!.summary).toBe('After');
expect(out).not.toContain('folded onto a second line');
});
test('removing a folded property takes all of it', () => {
const folded = ICS.replace('RRULE:FREQ=WEEKLY', 'RRULE:FREQ=WEEKLY\r\n ;COUNT=10');
expect(setProperty(folded, 'RRULE', null)).not.toContain('COUNT=10');
});
test('a long new value is folded, and reads back whole', () => {
const long = 'y'.repeat(300);
const out = setProperty(ICS, 'SUMMARY', long);
expect(out.split('\r\n').every((l) => Buffer.byteLength(l, 'utf8') <= 75)).toBe(true);
expect(parseEvents(out)[0]!.summary).toBe(long);
});
test('repeated edits do not accumulate', () => {
let out = ICS;
for (const v of ['one'.repeat(40), 'two'.repeat(40), 'three']) out = setProperty(out, 'SUMMARY', v);
expect(parseEvents(out)[0]!.summary).toBe('three');
});
});
web/dav/useDavEdit.ts
+51 -119
View File
@@ -3,86 +3,18 @@ import { useQueryClient } from '@tanstack/react-query';
import { useClient } from 'hooks/useClient';
/**
* Editing and deleting one DAV object, without losing what this app does not understand.
* Creating, changing and deleting one DAV object, in FIELDS.
*
* ── Read, patch, put — never rebuild ──
* Nothing here knows what an .ics looks like, and that is the point. This used to read the object's
* text, patch it in the browser and put it back, which meant the browser carried its own copy of the
* iCalendar escaping and 75-octet folding rules — a second place to be subtly wrong about a format
* neither screen displays. That work moved to the sidecar (see sidecar/patch.ts), which held the only
* other copy, and the agent skill now calls the same routes instead of writing a third one in bash.
*
* An event or a card is a file with far more in it than these screens show: alarms, attendees,
* recurrence rules, categories, every `X-` property the client that wrote it invented. Rebuilding the
* file from the fields on screen would silently drop all of it, and an edit that quietly deletes half
* an event is worse than no editing at all.
*
* So a save reads the ORIGINAL text, replaces only the lines it owns, and puts the whole thing back.
* Verified on a real event: 22 lines before, 22 after, one changed.
*
* ── The href is the address, and it comes from the listing ──
*
* Not `<uid>.ics`. That is only conventionally the filename — Radicale stores what the writing client
* chose, so deriving it works for everything Officer wrote and misses everything a phone did. The
* listing returns the real href; this hands it straight back.
* The guarantee it makes is unchanged: a patch replaces only the lines it owns, so alarms, attendees,
* recurrence rules and every unknown `X-` property survive an edit made from a form that cannot show them.
*/
/**
* Replace a property's line, or append it when the file has none. Handles `PROP:` and `PROP;PARAM:`.
*
* A property is not always ONE line. RFC 5545 folds anything over 75 octets onto continuation lines that
* start with a space, so a long description is one property spread over several. Replacing only the first
* line leaves the rest behind, and they then fold onto whatever was written in its place — the new value
* silently grows the tail of the old one. So the whole run goes, and the whole run is rewritten.
*/
export function setProperty(raw: string, prop: string, value: string | null): string {
const lines = raw.split(/\r?\n/);
const at = lines.findIndex((l) => l === prop || l.startsWith(`${prop}:`) || l.startsWith(`${prop};`));
// Everything folded onto the property belongs to it.
let after = at + 1;
while (at !== -1 && after < lines.length && /^[ \t]/.test(lines[after]!)) after++;
if (value === null) return at === -1 ? raw : [...lines.slice(0, at), ...lines.slice(after)].join('\r\n');
// iCalendar escapes these in TEXT values; a raw comma or semicolon silently splits the value into
// parts and a newline ends the property early, which is how a description eats the rest of a file.
const escaped = value.replace(/\\/g, '\\\\').replace(/\n/g, '\\n').replace(/([,;])/g, '\\$1');
if (at !== -1) {
// Keep any parameters the line already carried — `DTSTART;TZID=…` must not become `DTSTART:`.
const params = /^[A-Z-]+(;[^:]*)?:/.exec(lines[at]!)?.[1] ?? '';
return [...lines.slice(0, at), fold(`${prop}${params}:${escaped}`), ...lines.slice(after)].join('\r\n');
}
// Appended inside the component, immediately after UID, so it lands in the right block of a file that
// holds more than one.
const uidAt = lines.findIndex((l) => l.startsWith('UID:'));
const insertAt = uidAt === -1 ? Math.max(0, lines.length - 2) : uidAt + 1;
return [...lines.slice(0, insertAt), fold(`${prop}:${escaped}`), ...lines.slice(insertAt)].join('\r\n');
}
/**
* Fold a content line at 75 OCTETS, per RFC 5545 §3.1.
*
* Octets rather than characters, and broken between code points, so an accent in a pasted title is not
* cut in half. Deliberately a second copy of the sidecar's `fold` rather than an import: this package is
* a browser bundle and the sidecar is a server process, and the existing rule in this plugin is that the
* two MIRROR each other's shapes instead of sharing code across that boundary.
*/
function fold(line: string): string {
const encoder = new TextEncoder();
const out: string[] = [];
let current = '';
let bytes = 0;
for (const ch of line) {
const size = encoder.encode(ch).length;
if (bytes + size > 75) {
out.push(current);
current = ' ';
bytes = 1;
}
current += ch;
bytes += size;
}
out.push(current);
return out.join('\r\n');
}
export type NewEvent = {
summary: string;
location?: string;
@@ -92,6 +24,29 @@ export type NewEvent = {
allDay: boolean;
};
export type NewContact = {
fullName: string;
emails?: string[];
phones?: string[];
org?: string;
title?: string;
};
/** What a patch may set. Absent leaves a field alone; `null` removes it. */
export type ItemPatch = {
summary?: string;
location?: string | null;
description?: string | null;
start?: string;
end?: string;
allDay?: boolean;
fullName?: string;
emails?: string[];
phones?: string[];
org?: string | null;
title?: string | null;
};
/** `busy` holds the href being written; a create has no href yet, so it gets a sentinel of its own. */
export const CREATING = 'creating';
@@ -103,58 +58,35 @@ export function useDavEdit(invalidateKey: unknown[]) {
const refresh = () => qc.invalidateQueries({ queryKey: invalidateKey });
/** The object's original text, so a caller can patch rather than rebuild. */
const readRaw = async (href: string): Promise<string> => {
const res = await client.get<{ data: string }>(`/caldav/_officer/item?href=${encodeURIComponent(href)}`);
return res.data;
};
const save = async (href: string, patch: (raw: string) => string) => {
setBusy(href);
/** Every verb has the same shape: mark busy, do it, refresh, and report rather than throw. */
const run = async (key: string, fallback: string, work: () => Promise<unknown>) => {
setBusy(key);
setError(null);
try {
const raw = await readRaw(href);
await client.put('/caldav/_officer/item', { href, data: patch(raw) });
await refresh();
} catch (err) {
setError(err instanceof Error ? err.message : 'Could not save.');
} finally {
setBusy(null);
}
};
const remove = async (href: string) => {
setBusy(href);
setError(null);
try {
await client.delete('/caldav/_officer/item', { href });
await refresh();
} catch (err) {
setError(err instanceof Error ? err.message : 'Could not delete.');
} finally {
setBusy(null);
}
};
/**
* A new event. The BODY is built by the sidecar, not here — a browser has no business generating a
* UID, a DTSTAMP and a VTIMEZONE-free UTC timestamp, and there is exactly one correct answer for each,
* which belongs next to the parser that has to read them back.
*/
const create = async (collection: string, event: NewEvent) => {
setBusy(CREATING);
setError(null);
try {
await client.post('/caldav/_officer/event', { collection, ...event });
await work();
await refresh();
return true;
} catch (err) {
setError(err instanceof Error ? err.message : 'Could not create.');
setError(err instanceof Error ? err.message : fallback);
return false;
} finally {
setBusy(null);
}
};
return { save, remove, create, readRaw, busy, error };
return {
busy,
error,
save: (href: string, patch: ItemPatch) =>
run(href, 'Could not save.', () => client.patch('/caldav/_officer/item', { href, ...patch })),
remove: (href: string) => run(href, 'Could not delete.', () => client.delete('/caldav/_officer/item', { href })),
createEvent: (collection: string, event: NewEvent) =>
run(CREATING, 'Could not create.', () => client.post('/caldav/_officer/event', { collection, ...event })),
createContact: (collection: string, contact: NewContact) =>
run(CREATING, 'Could not create.', () => client.post('/caldav/_officer/contact', { collection, ...contact })),
};
}