repositories / dotfiles

dotfiles

bugabingas dorkfiles

owned by bugabinga

docs(nuguland): fold iCal parser research into CalDAV spec

34d7749807bd8bc3c21fefd3e4281ee32e082b7b

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

- Single-pass unescape regex (chained .replace mishandles \\n adjacency)
- RFC 5545 unfold: split CR/LF/CRLF, strip one WS, never trim
- Split name;params from value on first unquoted colon
- VTODO query MUST NOT use <C:expand> (Nextcloud #45333 drops tasks)
- Cite RFC 5545 + node-ical/ical.js basis; snippets are clean-room

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Changed files (1)

quickshell/nuguland/docs/superpowers/specs/2026-06-28-caldav-calendar-design.md

Modified
159 159 ### 5.3 Tasks — REPORT calendar-query (per VTODO calendar)
161 -Same shape with `<c:comp-filter name="VTODO">`. No `<c:expand>` (tasks rarely recur). Time-range on VTODO is unreliable across servers, so fetch the calendar's VTODOs and filter client-side by `DUE`/`DTSTART` within the window; tasks with no date are dropped (cannot be placed on the grid).
161 +Same shape with `<c:comp-filter name="VTODO">` and **no `<c:expand>`** — this is mandatory, not just unnecessary: Nextcloud's server-side expand is built around recurring VEVENTs and **drops VTODOs** ([nextcloud/server#45333](https://github.com/nextcloud/server/issues/45333)); expanding the task query would silently return nothing. Time-range filtering on VTODO is also unreliable across servers, so fetch the calendar's VTODOs and filter client-side by `DUE`/`DTSTART` within the window; tasks with no date are dropped (cannot be placed on the grid).
163 163 ### 5.4 One Process, all calendars
187 187 1. **Split** on the `@@CAL <href>\t<color>\t<kind>` delimiter to attribute each chunk to its calendar.
188 188 2. **Extract** each `<c:calendar-data>…</c:calendar-data>` text node via regex (per chunk).
189 189 3. **XML-entity-decode** the text: a small map for `&amp; &lt; &gt; &quot; &#39;` plus numeric `&#NN;` via `String.fromCharCode`. (`&#13;` → CR, then normalized away in unfolding.)
190 -4. **Split** into `BEGIN:VEVENT`/`BEGIN:VTODO` … `END:` blocks.
191 -5. **Unfold** continuation lines: normalize CRLF→LF, then a line beginning with space or tab is appended to the previous line.
192 -6. For each property, **unescape ICS text**: `\\n`→newline, `\\,`→`,`, `\\;`→`;`, `\\\\`→`\\`.
193 -7. Read `SUMMARY`, `UID`, and:
190 +4. **Unfold** (RFC 5545 §3.1) — split on `/\r\n|\r|\n/` (servers are inconsistent; don't assume CRLF), then for each following line whose first char is space or TAB, strip **exactly one** leading whitespace char and append to the previous line. Do **not** `trim()` continuation lines (kills intentional leading spaces).
191 + ```js
192 + // unfold: merge lines starting with one space/tab
193 + for (let i = 0; i < lines.length; i++) {
194 + while (i+1 < lines.length && /^[ \t]/.test(lines[i+1])) { lines[i] += lines[i+1].slice(1); lines.splice(i+1,1); }
196 + ```
197 +5. **Split** into `BEGIN:VEVENT`/`BEGIN:VTODO` … `END:` blocks.
198 +6. For each content line, split `name;params` from `value` on the **first unquoted colon**: `line.split(/:(?=(?:[^"]*"[^"]*")*[^"]*$)/)` — params (e.g. `TZID="…"`) may contain quoted colons.
199 +7. **Unescape ICS TEXT** (RFC 5545 §3.3.11) with a **single left-to-right pass**, not chained `.replace()` (a chain mis-handles adjacent backslashes like `\\n`). Only four escapes exist; colon is never escaped in values:
200 + ```js
201 + // \\ \; \, collapse to the bare char; \n or \N → newline
202 + const unescapeText = v => v.replace(/\\(.)/g, (_, c) => (c === 'n' || c === 'N') ? '\n' : c);
203 + ```
204 +8. Read `SUMMARY`, `UID`, and:
194 205 - **Timed** (`DTSTART:…Z`): `startMs`/`endMs` as **UTC epoch ms** (parse the `yyyymmddThhmmssZ` form and `Date.UTC(...)`); `allDay=false`.
195 206 - **All-day** (`DTSTART;VALUE=DATE:yyyymmdd`): `date` and `endDate` (iCal **exclusive** end → covered days are `date … endDate-1`); `allDay=true`. No timezone math.
196 207 - **Task** (VTODO): `kind="task"`, `date` from `DUE` (or `DTSTART`); `done` from `STATUS:COMPLETED`/`PERCENT-COMPLETE:100`.
197 -8. Return an array of plain JS objects:
208 +9. Return an array of plain JS objects:
200 211 { uid, summary, cal: "personal", color: "#5b8cff",
208 219 Parser must be defensive: unknown/garbage blocks are skipped, never throw (a parse error must not blank the whole calendar). Wrap the top-level parse in try/catch → on throw, treat as `offline` (keep last-good data).
221 +*Basis:* unfold/unescape/date rules verified against RFC 5545 §3.1/§3.3.4–5/§3.3.11 and the parsing approaches in node-ical (MIT) and kewisch/ical.js (MPL-2.0). The snippets above are clean-room reformulations (no license entanglement). Confirmed that Nextcloud's own stack (cdav-library + @nextcloud/calendar-js) follows the same split — WebDAV XML envelope → extract `calendar-data` → iCal parse — so we replace only the heavy iCal leaf with ~40 lines suited to flat, pre-expanded data.
212 225 ## 8. Status & error handling