From 4eb7c287971b87554229b4964dc78eb1f9f6434e Mon Sep 17 00:00:00 2001 From: Lucas Berger Date: Fri, 5 Jun 2026 17:50:23 -0400 Subject: [PATCH] =?UTF-8?q?docs(03-02):=20complete=20broker=20primitives?= =?UTF-8?q?=20plan=20=E2=80=94=20vevent.ts=20+=20write.ts=20GREEN?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .planning/ROADMAP.md | 4 +- .planning/STATE.md | 20 +-- .../03-02-SUMMARY.md | 119 ++++++++++++++++++ 3 files changed, 132 insertions(+), 11 deletions(-) create mode 100644 .planning/phases/03-event-write-back-pwa-install/03-02-SUMMARY.md diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index e78f820..5b1bbd5 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -101,7 +101,7 @@ Plans: **Wave 2** *(blocked on Wave 1)* -- [ ] 03-02-PLAN.md — TDD: VEVENT builder (vevent.ts, D-13 DATE/DATETIME + RRULE) + tsdav write wrappers (write.ts, D-12 broker boundary) +- [x] 03-02-PLAN.md — TDD: VEVENT builder (vevent.ts, D-13 DATE/DATETIME + RRULE) + tsdav write wrappers (write.ts, D-12 broker boundary) - [ ] 03-03-PLAN.md — Write API: POST/PATCH/DELETE events + GET sync-status, enqueue-only, D-03 ownership, D-04 edit-as-move pair (CAL-04/05/06/07) **Wave 3** *(blocked on Wave 2)* @@ -161,7 +161,7 @@ Note: Phase 4 depends only on Phase 1 and can begin as soon as Phase 1 is comple |-------|----------------|--------|-----------| | 1. Foundation + Broker Spike | 4/4 | Complete | 2026-06-04 | | 2. Calendar Display | 5/5 | Complete | 2026-06-05 | -| 3. Event Write-Back + PWA Install | 1/8 | In Progress| | +| 3. Event Write-Back + PWA Install | 2/8 | In Progress| | | 4. Shared Lists + Live Sync | 0/? | Not started | - | | 5. Web Push Notifications | 0/? | Not started | - | diff --git a/.planning/STATE.md b/.planning/STATE.md index 782db5b..58a09f1 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -3,14 +3,14 @@ gsd_state_version: 1.0 milestone: v1.0 milestone_name: milestone status: executing -stopped_at: Completed 03-01-PLAN.md -last_updated: "2026-06-05T21:41:20.635Z" -last_activity: 2026-06-05 -- Phase 03 execution started +stopped_at: Completed 03-02-PLAN.md +last_updated: "2026-06-05T21:50:11.190Z" +last_activity: 2026-06-05 progress: total_phases: 6 completed_phases: 2 total_plans: 17 - completed_plans: 10 + completed_plans: 11 percent: 33 --- @@ -26,11 +26,11 @@ See: .planning/PROJECT.md (updated 2026-06-03) ## Current Position Phase: 03 (event-write-back-pwa-install) — EXECUTING -Plan: 2 of 8 +Plan: 3 of 8 Status: Ready to execute -Last activity: 2026-06-05 -- Phase 03 execution started +Last activity: 2026-06-05 -Progress: [███░░░░░░░] 33% (2 of 6 phases complete) +Progress: [███████░░░] 65% ## Performance Metrics @@ -53,6 +53,7 @@ Progress: [███░░░░░░░] 33% (2 of 6 phases complete) *Updated after each plan completion* | Phase 03 P01 | 45 | 5 tasks | 8 files | +| Phase 03 P03-02 | 4 | 2 tasks | 2 files | ## Accumulated Context @@ -69,6 +70,7 @@ Recent decisions affecting current work: - Real-time transport: Prefer SSE over WebSocket (proxy-resilient through Pangolin). SSE pass-through STILL UNVERIFIED — gate before Phase 4 (D-14). - Recurring events: Create + display only in v1 (CALDAV:expand on server side). Single-occurrence edit deferred to v1.x. - [Phase ?]: D-Task5-DDL: drizzle-kit push unsafe on MariaDB 11 (mysql dialect misreads metadata, schedules truncate). Additive DDL hand-applied; adopt drizzle-kit generate+migrate before next schema change. +- [Phase ?]: D-02-RRULE: use ICAL.Recur.fromString + ICAL.Property for RRULE serialization — addPropertyWithValue produces char-split output for RECUR types ### Pending Todos @@ -97,6 +99,6 @@ Recent decisions affecting current work: ## Session Continuity -Last session: 2026-06-05T21:41:20.623Z -Stopped at: Completed 03-01-PLAN.md +Last session: 2026-06-05T21:50:11.159Z +Stopped at: Completed 03-02-PLAN.md Resume file: None diff --git a/.planning/phases/03-event-write-back-pwa-install/03-02-SUMMARY.md b/.planning/phases/03-event-write-back-pwa-install/03-02-SUMMARY.md new file mode 100644 index 0000000..8120d81 --- /dev/null +++ b/.planning/phases/03-event-write-back-pwa-install/03-02-SUMMARY.md @@ -0,0 +1,119 @@ +--- +phase: 03-event-write-back-pwa-install +plan: 02 +subsystem: broker, caldav +tags: [ical.js, tsdav, vevent-builder, caldav-write, d-13, tdd] + +# Dependency graph +requires: + - phase: 03-event-write-back-pwa-install + plan: 01 + provides: Wave 0 RED test scaffold (vevent.test.ts, write.test.ts), calendarOutbox schema + +provides: + - buildVeventString(NewEventParams) → { uid, icsString } in broker/vevent.ts + - createCalendarEvent / updateCalendarEvent / deleteCalendarEvent in broker/write.ts + - RRULE_PRESETS map and NewEventParams interface exported from vevent.ts + +affects: [03-03, 03-04] + +# Tech tracking +tech-stack: + added: [] + patterns: + - "ICAL.Recur.fromString + new ICAL.Property('rrule') for RRULE serialization (addPropertyWithValue on string produces char-split output)" + - "ICAL.Time({ isDate: true }, ICAL.Timezone.localTimezone) for all-day DATE values (TS types require 2-arg constructor)" + - "ICAL.Time.fromJSDate(date, true) for timed UTC events (useUTC=true → Z suffix, no TZID)" + - "null etag passed as '' in tsdav calendarObject (safe default; tsdav skips If-Match header)" + +key-files: + created: + - apps/api/src/broker/vevent.ts + - apps/api/src/broker/write.ts + modified: [] + +key-decisions: + - "D-02-RRULE: ICAL.Recur.fromString + ICAL.Property('rrule') is required for correct RRULE serialization. ICAL.Component.addPropertyWithValue('rrule', string) treats the string as a TEXT value and serializes each character individually — unusable. Use ICAL.Recur.fromString → prop.setValue(recur) → vevent.addProperty(prop)." + - "D-02-DATE-ZONE: ICAL.Time constructor TypeScript signature requires 2 args (data, zone). For all-day DATE values, isDate:true suppresses any TZID output regardless of which zone is passed. ICAL.Timezone.localTimezone is the safe choice; it satisfies the type without adding TZID to DATE properties." + +# Metrics +duration: ~4min +completed: 2026-06-05 +--- + +# Phase 03 Plan 02: Broker Primitives — vevent.ts + write.ts Summary + +**VEVENT builder and tsdav write wrappers implemented GREEN against Wave 0 RED scaffolds — all 13 broker tests pass, tsc clean** + +## Performance + +- **Duration:** ~4 min +- **Started:** 2026-06-05T21:44Z +- **Completed:** 2026-06-05T21:48Z +- **Tasks:** 2 +- **Files created:** 2 + +## Accomplishments + +- Implemented `buildVeventString(params: NewEventParams): { uid: string; icsString: string }` in `broker/vevent.ts` using ical.js ICAL.Component/ICAL.Time APIs +- D-13 DATE/DATETIME split: all-day events use `ICAL.Time({ isDate: true })` → VALUE=DATE (no TZID, no time); timed events use `ICAL.Time.fromJSDate(date, true)` → DTSTART:...Z (no TZID) +- RRULE correctly serialized via `ICAL.Recur.fromString` + `ICAL.Property` (not `addPropertyWithValue` which produces char-split output) +- Exported `NewEventParams` interface and `RRULE_PRESETS` map (daily/weekly/monthly/yearly preset strings) +- Implemented `createCalendarEvent`, `updateCalendarEvent`, `deleteCalendarEvent` in `broker/write.ts` as the sole CalDAV write boundary (D-12) +- All etag null-coalescion to `''` so tsdav safely omits the If-Match header rather than crashing + +## Task Commits + +1. **Task 1: GREEN — buildVeventString** — `b23b959` (feat) +2. **Task 2: GREEN — tsdav write wrappers + vevent.ts TS fix** — `a1243c1` (feat) + +## Files Created + +- `apps/api/src/broker/vevent.ts` — buildVeventString, NewEventParams, RRULE_PRESETS (117 lines) +- `apps/api/src/broker/write.ts` — createCalendarEvent, updateCalendarEvent, deleteCalendarEvent (99 lines) + +## Decisions Made + +- **D-02-RRULE:** `ICAL.Component.addPropertyWithValue('rrule', string)` treats the raw string as a TEXT value and serializes character-by-character (e.g., `RRULE:0=F;1=R;2=E;3=Q...`). The correct approach is `ICAL.Recur.fromString(rruleString)` → `prop = new ICAL.Property('rrule')` → `prop.setValue(recur)` → `vevent.addProperty(prop)`. This produces the correct `RRULE:FREQ=WEEKLY;BYDAY=MO` output. + +- **D-02-DATE-ZONE:** ical.js `ICAL.Time` TypeScript types require 2 arguments `(data: timeInit, zone: Timezone)`. For all-day DATE values, `isDate: true` in the data object suppresses any TZID/time output regardless of the zone passed. `ICAL.Timezone.localTimezone` is the appropriate second arg — it satisfies the type and has no effect on DATE serialization. + +## Deviations from Plan + +### Auto-fixed Issues + +**1. [Rule 1 - Bug] RRULE serialization via addPropertyWithValue produces character-split output** +- **Found during:** Task 1 — first test run showed `RRULE:0=F;1=R;2=E;3=Q...` instead of `RRULE:FREQ=WEEKLY;BYDAY=MO` +- **Issue:** `vevent.addPropertyWithValue('rrule', string)` passes a JavaScript string where ical.js expects a RECUR value type. ical.js iterates the string object properties (0, 1, 2...) and serializes each character as a key-value pair. +- **Fix:** Use `ICAL.Recur.fromString(params.rruleString)` to parse the string into a RECUR value object, then `new ICAL.Property('rrule')` + `prop.setValue(recur)` + `vevent.addProperty(prop)`. +- **Files modified:** `apps/api/src/broker/vevent.ts` +- **Commit:** `a1243c1` (combined with Task 2) + +**2. [Rule 1 - Bug] ICAL.Time constructor TypeScript type error (2 args required)** +- **Found during:** Task 2 — `tsc --noEmit` reported `Expected 2 arguments, but got 1` for `new ICAL.Time({ isDate: true })` calls +- **Issue:** ical.js TypeScript declarations define `constructor(data: timeInit, zone: Timezone)` as requiring both arguments, though the JavaScript implementation accepts 1. +- **Fix:** Pass `ICAL.Timezone.localTimezone` as the second arg. For `isDate: true` DATE values, the zone has no effect on serialization — it does not add TZID to the property. +- **Files modified:** `apps/api/src/broker/vevent.ts` +- **Commit:** `a1243c1` + +## Known Stubs + +None — both files are fully implemented primitives. No hardcoded placeholder values. + +## Threat Surface Scan + +No new network endpoints or auth paths introduced. `broker/write.ts` is a low-level CalDAV I/O primitive called only by the outbox worker (planned in 03-03). The T-03-03 (ical.js escaping) and T-03-04 (etag sourced server-side) mitigations from the threat model are implemented as designed. + +## Self-Check: PASSED + +- `apps/api/src/broker/vevent.ts` — exists (confirmed) +- `apps/api/src/broker/write.ts` — exists (confirmed) +- Commit `b23b959` — exists (git log confirmed) +- Commit `a1243c1` — exists (git log confirmed) +- `pnpm --filter @familysync/api exec vitest run tests/broker/vevent.test.ts` — 7/7 PASS +- `pnpm --filter @familysync/api exec vitest run tests/broker/write.test.ts` — 6/6 PASS +- `pnpm --filter @familysync/api exec tsc --noEmit` — clean (no errors) + +--- +*Phase: 03-event-write-back-pwa-install* +*Completed: 2026-06-05*