calendula/docs/superpowers/plans/2026-06-18-06-ics-import.md

Calendula - Plan 06: ICS Import (v2.7, Branch 2 von 2)

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Die Lese-Hälfte des .ics-Themas, aufgesetzt auf den Writer aus Branch 1 (feat/ics-export, gemerged in release/v2.7.0). Calendula parst RFC-5545-Dateien und führt sie über zwei Wege ein: eine einzelne VEVENT öffnet das vorausgefüllte Erstellen-Formular (Review vor dem Speichern), eine Datei mit vielen Events geht in einen Bulk-Import mit Ziel-Kalender-Auswahl und Ergebnis-Report. Damit schließt sich der Backup→Restore-Kreis für lokale Kalender. Beide Branches landen in einem Release v2.7.0. ./gradlew lint test assembleDebug bleibt grün; Release erst nach On-Device-Review.

Architecture: IcsParser lebt rein in domain/ics/ neben IcsWriter — kein Android, JVM-testbar, symmetrisch zum Writer. Ausgabe ist ein IcsParseResult (events: List<ParsedIcsEvent> + warnings: List<String>). ParsedIcsEvent ist die Parse-Variante von IcsEvent (gleiche Felder, aber uid: String? — eine eingelesene VEVENT kann ohne UID kommen). Zwei Adapter: ParsedIcsEvent.toEventForm(zone) (Einzel-Öffnen → EventForm) und eine Repository-Methode importEvents(targetCalendarId, events) → ImportSummary (Bulk). Datei-IO (Uri lesen, Intent) liegt in data/ics/ bzw. der Activity/Compose-Schicht; Routing 1-vs-viele entscheidet anhand der geparsten Event-Anzahl.

Liberal-in/strict-out (Leitprinzip): unbekannte Properties, fremde VTIMEZONE-Blöcke und RECURRENCE-ID-Ausnahmen werden übersprungen und im Report vermerkt, nie still verschluckt; ein einzelnes kaputtes VEVENT lässt den Rest der Datei durch.

Leitentscheidungen:

1. Parse-Mechanik (Umkehr von IcsText): zuerst Unfolding (CRLF + Space/Tab → wegfalten), dann pro Zeile NAME[;params]:value zerlegen, TEXT-Werte unescapen (\\ \; \, \n). Eine reine, einzeln getestete Schicht (IcsLineParser), nicht ad hoc im Walker.
2. Datum/Zeit-Parsing (Umkehr der Writer-Zeitzonenregel):
   • VALUE=DATE (YYYYMMDD) → all-day, Instant auf UTC-Mitternacht (wie der Provider all-day speichert), exklusives DTEND bleibt exklusiv.
   • …T…Z → UTC-Instant.
   • …T… mit TZID=<zone> → lokale Wandzeit in der Zone, aufgelöst gegen die OS-tz-Datenbank (TimeZone.of); unbekannte/fehlende TZID → Gerätezone als Fallback (+ Warnung).
   • Kein VTIMEZONE-Parsing — TZID wird gegen die OS-DB aufgelöst (s. Branch-1 Entscheidung); ein VTIMEZONE-Block wird übersprungen (Warnung nur, wenn seine TZID nicht in der OS-DB ist).
3. Routing 1-vs-viele: genau eine VEVENT → vorausgefülltes Erstellen-Formular (ParsedIcsEvent.toEventForm, calendarId=null → Formular wählt wie gehabt den zuletzt genutzten Kalender vor). Mehr als eine → Bulk-Import-Screen (Ziel-Kalender-Picker, nur beschreibbare). Leere Datei → freundlicher „nichts gefunden"-Hinweis.
4. UID-Dedup beim Bulk-Import: vor dem Insert die vorhandenen Events.UID_2445 des Ziel-Kalenders lesen; eine eingelesene UID, die schon existiert, wird übersprungen (gezählt als „bereits vorhanden"). v1: skip-not-update — kein Überschreiben, das hält den Restore idempotent und verlustfrei. Events ohne UID bekommen beim Insert eine frische (UUID@calendula, wie insertEvent).
5. Empfang via Intent: Manifest-ACTION_VIEW/SEND mit MIME text/calendar (+ .ics-Pfadmuster für file/content-Schemes). MainActivity (singleTop, wie beim Reminder-Tap) liest den Uri, parst, und reicht das Ergebnis als Compose-State an CalendarHost (gleiches Key-Muster wie der Notification-Deep-Link).
6. Reminder/Status/Transp zurück: VALARM TRIGGER (negatives -PT…, PT0…) → Lead-Minuten; STATUS/TRANSP → EventStatus/Availability. DURATION-statt-DTEND über parseRfc2445DurationMillis (existiert aus Branch 1). Attendees werden nicht importiert (kein Modell; Warnung wenn vorhanden).

Recherche-Befunde (Codebase, 2026-06-18 — aus Branch 1):

• IcsText.escapeText/foldLine + IcsWriter existieren; Parser spiegelt sie.
• parseRfc2445DurationMillis (in IcsExportMapper.kt) parst die Provider-DURATION-Formen inkl. des nicht-standardkonformen P<n>S.
• EventForm (Domain): Zeiten als LocalDateTime in Gerätezone, calendarId nullable; das Formular wählt bei null den zuletzt genutzten Kalender vor.
• insertEvent schreibt bereits Events.UID_2445; für den Import muss eine vorgegebene UID durchgereicht werden (Insert-Variante / Parameter).

---

Tasks

Parser-Engine (domain/ics/, reine Kotlin, JVM-Tests):

• IcsText: unescapeText + unfold(lines) ergänzen (+ Test)
• IcsLineParser: NAME;PARAM=v;PARAM=v:VALUE → (name, params-map, value); Param-Werte ggf. in Quotes; Test (Kantenfälle: Doppelpunkt im Wert, gequotete Params)
• ParsedIcsEvent (wie IcsEvent, aber uid: String?) + Datum/Zeit-Parser (VALUE=DATE / …Z / TZID → Instant + isAllDay + zoneId)
• IcsParser.parse(text) → IcsParseResult(events, warnings): VCALENDAR/ VEVENT-Walk, skip-and-report für RECURRENCE-ID/unbekannte VTIMEZONE/ Attendees; ein defektes VEVENT killt nicht den Rest. Round-trip-Test gegen IcsWriter-Ausgabe (all-day, getimt, wiederkehrend+TZID, Reminder) + Fremd-Quirks (gefaltete Zeilen, fehlende UID, PT…-Trigger)

Datenschicht (data/calendar/ + data/ics/):

• ParsedIcsEvent.toEventForm(zone) (Einzel-Öffnen → EventForm); Test
• Datasource: existingUids(calendarId) (Query Events.UID_2445) + insertImported(event, calendarId) (Insert mit vorgegebener/erzeugter UID)
• Repository importEvents(targetCalendarId, events) → ImportSummary (imported / skippedDuplicate / skippedUnsupported); UID-Dedup; Test mit Fake-Datasource
• IcsImporter (data/ics/): Uri → Text lesen (UTF-8, contentResolver)

Intent + Routing:

• Manifest: ACTION_VIEW/ACTION_SEND, MIME text/calendar, .ics- Pfadmuster (file/content); MainActivity parst eingehenden Uri
• Routing in CalendarHost: 1 Event → Erstellen-Formular vorausgefüllt; >1 → Bulk-Import-Screen; 0 → Hinweis

UI:

• Bulk-Import-Screen: Ziel-Kalender-Picker (OptionCard, nur beschreibbare), Anzahl/Vorschau, Import-Button → ImportSummary als Ergebnis
• Einzel-Öffnen: EventEditScreen mit vorausgefülltem Formular (neuer Prefill-Pfad im EventEditViewModel, ohne eventId)
• Strings DE+EN: Import-Titel, Ziel-Auswahl, Ergebnis-Plurals (importiert / übersprungen-vorhanden / übersprungen-nicht-unterstützt), leere-Datei-Hinweis

Abschluss:

• ./gradlew lint test assembleDebug grün
• CHANGELOG ([Unreleased]), ROADMAP/STATE; v2.7 cut erst wenn beide Branches gemerged sind und On-Device-Review durch ist