repositories / dotfiles

dotfiles

bugabingas dorkfiles

owned by bugabinga

docs(nuguland): CalDAV spec parses in QML/JS, no Python

12c3fac3ddb20b6af6fcbf0116c0e5fdf1eab632

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

curl emits raw XML; ICS parsing (unfold/unescape/entity-decode/tz) moves
to a sibling caldav.js. Removes the external interpreter dependency.

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
13 13 - A month grid (6 weeks) showing real events as **dots** (timed single-day), **pills** (all-day single-day), and **spanning bands** (multi-day).
14 14 - A **today agenda** listing today's events and due tasks.
15 -- Data pulled from Nextcloud CalDAV via `curl` (a new `CalDav.qml` service), parsed by an embedded Python script into JSON.
15 +- Data pulled from Nextcloud CalDAV via `curl` (a new `CalDav.qml` service), parsed in QML/JS (no external interpreter).
16 16 - A **first-run setup popup** that captures server URL + username + app-password, persists the non-secret parts to a config file and the password to the system keyring.
17 17 - Graceful degradation when the network, keyring, or `secret-tool` is unavailable.
26 26 |-------|----------|
27 27 | HTTP transport | `curl` via `Process` (Qt QML `XMLHttpRequest` rejects the `REPORT` verb — proven; see §11) |
28 28 | Recurrence | Server-side `<C:expand>` in the `REPORT` — no client recurrence engine |
29 +| Parsing | QML/JS only — no Python/external interpreter (`curl` emits raw XML; JS parses) |
29 30 | Service boundary | New `CalDav.qml` (network IO), separate from `Time.qml` (local clock) |
30 31 | Calendars | All event calendars + Reminders (VTODO), color-coded per Nextcloud `calendar-color`; auto-discovered via PROPFIND (not hardcoded) |
31 32 | Tasks (VTODO) | Shown: dot on due day + agenda row marked `○` (read-only) |
51 52 config (statePath caldav.json) ─────┤
52 53 {url, username, calendars[]} ▼
53 54 CalDav.qml (new service, DI from shell.qml)
54 - • Process: sh -c "curl REPORT… | python3 parse"
55 - • StdioCollector → JSON.parse → events[] / tasks[]
55 + • Process: sh -c "curl REPORT… (raw XML out)"
56 + • StdioCollector → JS parse → events[] / tasks[]
56 57 • Timer(15min) + refresh() on popout open + initial
57 58 • status: ok | offline | needs-setup
58 59 • stateJson() (additive IPC contract)
71 72 - **`shell.qml`** — instantiates `CalDav`, injects it into `PopoutHost` (DI per [[nuguland-di-no-singleton]]); adds an IPC handler returning `caldav.stateJson()`.
72 73 - **`PopoutHost.qml` `clockContent`** — pure view over `caldav` props; renders grid + agenda.
73 74 - **`PopoutHost.qml` setup popup** — credential capture; writes config + stores secret; triggers `caldav.discoverAndFetch()`.
74 -- **Embedded Python parser** — string constant in `CalDav.qml` (mirrors the `desktopScanCode()` pattern in `Launcher.qml:511`), run as `python3 -c`.
75 +- **ICS parser** — plain QML/JS functions in `CalDav.qml` (or a sibling `caldav.js`). No external interpreter; `StdioCollector` hands raw XML text straight to JS.
134 135 PW="$(secret-tool lookup service caldav host "$CALDAV_HOST")" || { echo '__NO_SECRET__'; exit 0; }
135 136 [ -z "$PW" ] && { echo '__NO_SECRET__'; exit 0; }
136 -# …curl using -K - heredoc with user="$CALDAV_USER:$PW" … | python3 -c "$PARSE"
137 +# …curl using -K - heredoc with user="$CALDAV_USER:$PW" … (raw XML to stdout)
139 -If `secret-tool` is not installed, `sh` reports `command not found` → script prints `__NO_SECRET__` (caught by §8). The marker tokens (`__NO_SECRET__`) are how the QML side distinguishes "needs setup" from "network error" from valid JSON.
140 +If `secret-tool` is not installed, `sh` reports `command not found` → script prints `__NO_SECRET__` (caught by §8). The marker tokens (`__NO_SECRET__`) are how the QML side distinguishes "needs setup" from "network error" from valid response. The script emits **raw XML** (concatenated per calendar, §5.4); all parsing happens in JS.
141 142 ### 5.1 Discovery — PROPFIND (Depth 1)
162 163 ### 5.4 One Process, all calendars
164 -A single `Process` runs a loop over enabled calendar hrefs (passed as a newline-delimited env var), concatenating raw responses with a delimiter line `@@CAL <href>\t<color>\t<kind>`; the Python parser splits on it and tags each event with its calendar color/kind. One `StdioCollector` → one `JSON.parse`.
165 +A single `Process` runs a loop over enabled calendar hrefs (passed as a newline-delimited env var), concatenating raw responses with a delimiter line `@@CAL <href>\t<color>\t<kind>`; the JS parser splits on it and tags each event with its calendar color/kind. One `StdioCollector` → one JS parse pass.
182 -## 7. ICS parsing (Python, embedded)
183 +## 7. ICS parsing (QML/JS)
184 -Input: the XML `REPORT`/`PROPFIND` responses (calendar-data is XML-text-encoded). Steps, in order — all required (the sample has 116 folded lines and `&quot;`/`&#13;` entities):
185 +Plain JS functions (no external interpreter). Input: the raw XML `REPORT`/`PROPFIND` text from `StdioCollector` (calendar-data is XML-text-encoded). QML has no `DOMParser` global, so calendar-data text nodes are regex-extracted — the structure is flat and the content is escaped, so this is safe here. Steps, in order — all required (the sample has 116 folded lines and `&quot;`/`&#13;` entities):
186 -1. **Extract** each `<c:calendar-data>` text node (per `@@CAL` block).
187 -2. **XML-entity-decode** the text (`html.unescape` handles `&#13;`, `&quot;`, `&amp;`, …).
188 -3. **Split** into `BEGIN:VEVENT`/`BEGIN:VTODO` … `END:` blocks.
189 -4. **Unfold** continuation lines: a line beginning with space or tab is appended to the previous line (CRLF already normalized).
190 -5. For each property, **unescape ICS text**: `\\n`→newline, `\\,`→`,`, `\\;`→`;`, `\\\\`→`\\`.
191 -6. Read `SUMMARY`, `UID`, and:
192 - - **Timed** (`DTSTART:…Z`): emit `startMs`/`endMs` as **UTC epoch milliseconds**; `allDay=false`.
193 - - **All-day** (`DTSTART;VALUE=DATE:yyyymmdd`): emit `date` (and `endDate`, the iCal **exclusive** end → covered days are `date … endDate-1`); `allDay=true`. No timezone math.
187 +1. **Split** on the `@@CAL <href>\t<color>\t<kind>` delimiter to attribute each chunk to its calendar.
188 +2. **Extract** each `<c:calendar-data>…</c:calendar-data>` text node via regex (per chunk).
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:
194 + - **Timed** (`DTSTART:…Z`): `startMs`/`endMs` as **UTC epoch ms** (parse the `yyyymmddThhmmssZ` form and `Date.UTC(...)`); `allDay=false`.
195 + - **All-day** (`DTSTART;VALUE=DATE:yyyymmdd`): `date` and `endDate` (iCal **exclusive** end → covered days are `date … endDate-1`); `allDay=true`. No timezone math.
194 196 - **Task** (VTODO): `kind="task"`, `date` from `DUE` (or `DTSTART`); `done` from `STATUS:COMPLETED`/`PERCENT-COMPLETE:100`.
195 -7. Emit JSON array. Per-event fields:
197 +8. Return an array of plain JS objects:
197 -```json
198 -{ "uid": "...", "summary": "...", "cal": "personal", "color": "#5b8cff",
199 - "kind": "event"|"task", "allDay": false,
200 - "startMs": 1781888100000, "endMs": 1781891700000,
201 - "date": null, "endDate": null, "done": false }
199 +```js
200 +{ uid, summary, cal: "personal", color: "#5b8cff",
201 + kind: "event"|"task", allDay: false,
202 + startMs: 1781888100000, endMs: 1781891700000,
203 + date: null, endDate: null, done: false }
204 -QML side: timed → `new Date(startMs)` (auto-localizes); all-day/task → parse `date` as a plain local calendar date. Multi-day detection: `allDay && endDate` spanning >1 day, or timed event whose local start/end dates differ.
206 +Consumers: timed → `new Date(startMs)` (auto-localizes); all-day/task → parse `date` as a plain local calendar date (construct from y/m/d ints, no UTC). Multi-day detection: `allDay && endDate` spanning >1 day, or timed event whose local start/end dates differ.
206 -Parser must be defensive: unknown/garbage blocks are skipped, never throw (a parse error must not blank the whole calendar).
208 +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).
271 273 ## 13. File structure
273 -- **Create** `quickshell/nuguland/CalDav.qml` — service: config (FileView+JsonAdapter), discovery + fetch Process, embedded Python parser string, status, `discoverAndFetch()`, `refresh()`, `stateJson()`, `buildSegments()` pure helper (or a sibling JS file `caldav.js` if it keeps `CalDav.qml` focused).
275 +- **Create** `quickshell/nuguland/CalDav.qml` — service: config (FileView+JsonAdapter), discovery + fetch Process (curl, raw XML out), status, `discoverAndFetch()`, `refresh()`, `stateJson()`. ICS parsing + `buildSegments()` as pure JS helpers, in a sibling `caldav.js` to keep `CalDav.qml` focused and the parser independently testable.
274 276 - **Modify** `quickshell/nuguland/shell.qml` — instantiate `CalDav`, inject into `PopoutHost`, add IPC handler.
275 277 - **Modify** `quickshell/nuguland/PopoutHost.qml` — rewrite `clockContent` (grid + agenda + band overlay + stale indicator); add setup popup; trigger `caldav.refresh()` on clock popout open.
276 278 - `quickshell/nuguland/Time.qml` — unchanged (local clock/date stays its own concern).