Kopf frei
Persönliche Aufgabenverwaltung nach Getting Things Done von David Allen.
Installierbare Web-App (PWA) für Android, iPad und Windows. Die Daten liegen auf dem Gerät; zwischen Geräten werden sie verschlüsselt über ein privates GitHub-Repository abgeglichen.
Neue Versionen landen zuerst in der Test-App und kommen erst nach Freigabe in die Live-App.
Funktionen (Version 0.11.0)
- Inbox mit Schnellerfassung (Plus-Knopf oder Taste
N)
- Klär-Dialog nach dem Ablaufdiagramm des Buchs
- Kontexte als Symbole (Computer, Telefon, Unterwegs, Zuhause, Büro, Besprechung; eigene Kontexte mit Etikett und Namen)
- Listen: Nächste Schritte (Kontext-Filter), Fristen (nur Aufgaben), Projekte, Warten auf, Wiedervorlage, Irgendwann/Vielleicht, Referenz, Erledigt, Papierkorb
- Projekte mit Ziel, Frist und Farbe; Schritte nach Frist sortiert oder per Griff ⋮⋮ selbst geordnet (Warndreieck, wenn die Reihenfolge einer Frist widerspricht); Frist gleich beim Hinzufügen; beim Erledigen des letzten Schritts fragt die App nach dem nächsten
- Fälligkeitsdatum (Fahne) direkt in der Karte, Wiedervorlage („Nachfassen“ mit Glocke, „Erst ab“ mit Mond), alle in gleichen Boxen auf einer Linie; im Kontext-Platz Sanduhr für „Warten auf“, Fragezeichen ohne Kontext
- Handy: kompakte Karten (alles in einer Zeile unter dem Titel)
- Rückgängig (3 Sekunden) nach Erledigen, Löschen, Verschieben, Klären und Projektstatus
- Wischen zum Löschen: Karte nach links wischen → „Löschen“ legt die Aufgabe in den Papierkorb (3 Sekunden Rückgängig). Im Papierkorb kein Wischen; endgültig erst mit „Papierkorb leeren“.
- Projekt löschen nur in der Projektansicht, mit Bestätigung: Projekt und alle seine Aufgaben werden endgültig gelöscht, auch ein Schritt, den ein anderes Gerät gleichzeitig hinzugefügt hat.
- Sync-Konflikte: Bearbeiten speichert nur geänderte Felder; endgültig Gelöschtes bleibt auf allen Geräten gelöscht.
- Karten-Design in Solarized, Hell/Dunkel/System umschaltbar
- Sync über ein privates GitHub-Repository, Ende-zu-Ende verschlüsselt
- Zurück auf früheren Stand: Einstellungen → Stand vor einem Update, Ende eines Tages oder eigener Zeitpunkt. Nichts wird gelöscht, die App gleicht mit neuen Änderungen aus; lässt sich selbst wieder rückgängig machen.
- Verschlüsseltes Backup als Datei
- Update-Hinweis: Neue Versionen werden beim Öffnen erkannt und auf Knopfdruck installiert
Sicherheit
| Was | Wo | Schutz |
|---|
| Aufgaben, Projekte | Gerät (IndexedDB) | bleibt lokal |
| Sync-Daten | privates Repo head-space-data | AES-256-GCM, Schlüssel aus Passphrase (PBKDF2-SHA256, 600'000 Runden) |
| Sync-Schlüssel | Gerät | als nicht exportierbarer Schlüssel gespeichert |
| GitHub-Token | nur auf dem Gerät | Fine-grained Token, nur für head-space-data, nur „Contents“ |
| App-Code | öffentliches Repo head-space | enthält keine Daten |
Die App lädt keinen fremden Code (keine Abhängigkeiten) und erlaubt per Content-Security-Policy nur Verbindungen zu sich selbst und zu api.github.com.
Sync einrichten
- Token erstellen auf github.com: Settings → Developer settings → Personal access tokens → Fine-grained tokens → Generate new token
- Repository access: Only select repositories →
head-space-data
- Permissions → Repository permissions → Contents: Read and write
- In der App: Einstellungen → Synchronisation über GitHub: Benutzername, Repository, Token
- Erstes Gerät: Sync-Passphrase festlegen (gut aufbewahren). Weitere Geräte: dieselbe Passphrase eingeben.
Entwicklung
bun run build.mjs # baut dist/ und preview/kopf-frei.html
bun test # Unit-Tests in 1 s (Logik, Darstellung, alte Daten, Sync-Zufallstests, Verschlüsselung)
tests/run.sh # alles: Typen, Unit-Tests, End-to-End-Tests (Playwright Test, Ordner e2e/)
tests/run.sh projekte sync # Typen, Unit und nur e2e/projekte.spec.mjs und e2e/sync.spec.mjs
E2E_WEBKIT=1 tests/run.sh # zusätzlich WebKit (Safari-Kern) für @webkit-Tests, so läuft es auf GitHub
Jeder Push wird zuerst vollständig getestet und nur bei Erfolg veröffentlicht (GitHub Actions → GitHub Pages):
Branch test → Test-App, Branch main → Live-App. scripts/build-site.sh baut beide zusammen (Live nach site/, Test nach site/test/).
Geöffnete Apps zeigen danach „Neue Version verfügbar“.
Regeln für Erweiterungen (Rückwärtskompatibilität)
Die Daten sind ein Ereignis-Log: Jede Änderung ist ein Ereignis, der Zustand entsteht durch Abspielen. Damit bestehende Daten bei jedem Update weiter funktionieren:
- Ereignisse werden nie geändert oder gelöscht, nur neue angehängt.
- Neue Felder sind immer optional. Standardwerte für fehlende Felder in
normalizeItem / normalizeProject (src/store.ts).
- Felder werden nie umbenannt oder umgedeutet. Stattdessen ein neues Feld einführen.
- Unbekannte Felder und Ereignistypen bleiben erhalten, damit ältere App-Versionen auf anderen Geräten nichts kaputt machen.
- Datenbank-Upgrades (
DB_VERSION in src/db.ts) sind nur additiv: neue Speicher anlegen, nie löschen.
- Das Sync-Format (
kopf-frei.json, events/*.json) hat eine Versionsnummer. Eine ältere App lehnt neuere Formate ab, statt sie falsch zu lesen.
- Nach jeder Version ihre echten Daten einfrieren (
node scripts/alte-daten-einfrieren.mjs <commit> <version>); tests/unit/alte-daten.test.ts prüft, dass jede neue Version sie genau so liest.
Aufbau
src/
types.ts Datenmodell (Eintrag, Projekt, Ereignis)
db.ts IndexedDB, additive Migrationen
store.ts Ereignis-Log → Zustand, Aktionen, Backup, Kompatibilitätsregeln
sync.ts Verschlüsselter GitHub-Sync
crypto.ts Verschlüsselung (Web Crypto API)
icons.ts Kontext-Symbole
notes.ts Release Notes lesen („Was ist neu“ nach einem Update)
ui.ts Ansichten, Dialoge, Einstellungen
main.ts Start, Service Worker, Update-Hinweis
styles.css, cards.css Gestaltung
public/ Manifest, Service Worker, Icons
tests/unit/ Unit-Tests (bun test), alte Datenstände in tests/unit/alte-daten/
RELEASE-NOTES.md Neuerungen je Version (wird in die App eingebaut)
e2e/ End-to-End-Tests (Playwright Test), Aufbau in docs/TESTKONZEPT.md
.github/workflows/veroeffentlichen.yml Build und Veröffentlichung
