From 298da72b6d256d819cccb256c8bab24c892cae4d Mon Sep 17 00:00:00 2001 From: Florian Wilde Date: Sun, 26 Jul 2026 01:04:42 +0200 Subject: [PATCH] docs: v0.3.0 und v0.4.0 dokumentieren, Roadmap fortschreiben FEATURES beschreibt Markdown, Volltextsuche, PR- und Issue-Listen, den CI-Status samt Herkunft je Git-System, die Aktivitaetskurve inklusive ihrer Grenze, das Kanban-Board und das Testfundament. ROADMAP: sieben Punkte wandern zu den erledigten. Ganz oben steht jetzt der Ausbau der Tests auf Datenbank und Browser - das Fundament steht, die Schicht darueber fehlt und ich pruefe weiterhin von Hand. Danach Benachrichtigungen, die von CI-Status und Abgleich nun profitieren wuerden. Co-Authored-By: Claude Opus 5 (1M context) --- FEATURES.md | 59 ++++++++++++++++++++++++++++++++-- README.md | 3 ++ ROADMAP.md | 92 ++++++++++++++++++++--------------------------------- 3 files changed, 93 insertions(+), 61 deletions(-) diff --git a/FEATURES.md b/FEATURES.md index e9dafbb..a4dd644 100644 --- a/FEATURES.md +++ b/FEATURES.md @@ -107,10 +107,28 @@ Der Status ist **direkt auf der Projektkarte** umschaltbar, ohne den Detailberei - **Statusfilter** als Chips mit Trefferzähler, mehrere gleichzeitig kombinierbar. - **Sortierung** nach zuletzt geändert, Anlagedatum, Name, Fortschritt oder Priorität — Favoriten bleiben stets oben. -- **Zwei Ansichten**: freies Raster oder nach Status gruppierte Abschnitte. +- **Drei Ansichten**: freies Raster, nach Status gruppierte Abschnitte oder **Kanban**. +- **Volltextsuche über Notizen.** Die Suche im Board arbeitet auf den geladenen Projekten + (Name, Kurzbeschreibung, Tags, Repo-Pfad). Notizen liegen dort nicht vor — sie + mitzuladen würde die Seite aufblähen. Stattdessen sucht Postgres serverseitig mit + seiner deutschen Textsuche, entprellt ab zwei Zeichen. Treffer erscheinen als eigene + Liste mit hervorgehobener Fundstelle, die betroffenen Projekte werden zusätzlich + eingeblendet. Deutsche Stammformen greifen: „Webhook" findet auch „Webhooks". - **Archiv** ist standardmäßig ausgeblendet und per Schalter einblendbar. - **Leerzustände** mit direktem Einstieg statt einer leeren Fläche. +### Kanban + +Spalten je Status, Karten per Ziehen verschiebbar. Der Wechsel wird sofort angezeigt und +erst danach gespeichert; scheitert das Speichern, springt die Karte zurück. + +- Gezogen wird am Griff links, nicht an der ganzen Karte — so bleibt der Titel ein + normaler Link. +- Das Ziehen startet erst nach ein paar Pixeln Bewegung, damit Klicks weiter funktionieren. + Auf Touchgeräten nach kurzem Halten. +- Die Reihenfolge innerhalb einer Spalte folgt der gewählten Sortierung. Frei sortieren + ginge nur mit einer gespeicherten Position — bewusst nicht gebaut. + ### Projektkarte auf einen Blick Name und Favoritenstern · Kurzbeschreibung · Fortschrittsbalken · Provider-Badge · @@ -122,6 +140,10 @@ Anzahl Notizen · Warnung bei Sync-Fehler · Tags · Statusauswahl · Priorität ## 3. Notizen - **Beliebig viele Notizen pro Projekt**, mit optionalem Titel und mehrzeiligem Text. +- **Markdown wird dargestellt** — Überschriften, Listen, Tabellen, Codeblöcke, Zitate und + Links. Aus `- [ ] Aufgabe` werden echte Checklisten. Gilt auch für die Projekt- + beschreibung. Rohes HTML wird beim Rendern entfernt (`rehype-sanitize`) — der Inhalt + stammt vom Benutzer und wäre sonst ein XSS-Loch. - **Anpinnen** — angepinnte Notizen stehen oben und sind farblich hervorgehoben. - **Bearbeiten und Löschen** direkt in der Liste; Löschen fragt nach. - **Zeitstempel**: Anlagedatum immer, „bearbeitet vor …" nur bei echter Änderung. @@ -164,12 +186,28 @@ Firmen-Gitea nebeneinander. | --- | --- | | Repository | Voller Pfad, Beschreibung, Default-Branch, Sichtbarkeit, Größe, letzte Aktivität | | Kennzahlen | Stars, Forks, offene Issues, offene Pull-/Merge-Requests | +| **Pull-/Merge-Requests** | bis zu 50 offene, mit Nummer, Titel, Autor, Alter, Labels, Entwurfskennzeichnung und Link | +| **Issues** | bis zu 50 offene, gleiche Angaben. Bei GitHub und Gitea werden PRs herausgefiltert, die dort in derselben Liste stecken | +| **CI-Status** | Letzter Lauf auf dem Default-Branch: erfolgreich, fehlgeschlagen, läuft, wartet oder abgebrochen — mit Name und Link | | Branches | bis zu 50, mit SHA, Default-Markierung, Schutzstatus und (wo die API es liefert) letztem Commit | | Tags | bis zu 25, mit SHA, Nachricht und Datum | -| Commits | die letzten 15, mit Kurz-SHA, Nachricht, Autor, Datum und Link | +| Commits | die letzten 15 zur Anzeige; geholt werden 100 für die Aktivitätskurve | +| **Commit-Aktivität** | Balkenreihe der letzten Tage, auf Karte und Projektseite | | Releases | bis zu 10, inklusive Pre-Release- und Draft-Kennzeichnung | | Sprachen | Verteilung als Balken mit Prozentwerten | +Woher der CI-Status kommt: + +| System | Quelle | +| --- | --- | +| GitHub | `actions/runs` für den Default-Branch; Lauf-Status und Ergebnis werden zusammengeführt | +| GitLab | `pipelines` für den Default-Branch | +| Gitea | Kombinierter Commit-Status — deckt Gitea Actions **und** externe Systeme wie Woodpecker ab, anders als ein reiner Actions-Endpunkt, den ältere Instanzen nicht kennen | + +Zur Ehrlichkeit der Aktivitätskurve: geholt wird eine Seite mit 100 Commits. Reicht die +nicht über den ganzen Zeitraum, wird die Kurve auf den tatsächlich belegten Ausschnitt +gekürzt — eine Null zu zeichnen, wo wir schlicht nichts wissen, wäre falsch. + - **Snapshot-Prinzip**: Alle Daten werden in der Datenbank abgelegt. Das Dashboard bleibt ohne Netzverbindung oder bei erreichtem Rate-Limit vollständig nutzbar. @@ -328,7 +366,22 @@ nicht verloren gehen. Indizes auf Status, Verbindung und Änderungsdatum. - **Setup-Skript** erzeugt die `.env` samt zufälligem `APP_SECRET`. - **Seed-Daten** auf Wunsch, idempotent — mehrfaches Ausführen legt nichts doppelt an. -### 6.4 API +### 6.4 Tests + +`npm test` führt die Unit-Tests aus — reine Logik, kein DOM, keine Datenbank, unter einer +Sekunde: + +| Bereich | Was geprüft wird | +| --- | --- | +| `utils` | Slug-Erzeugung inklusive Umlauten und Längenbegrenzung, Tag-Aufbereitung, Kürzen, Zahlenformat | +| `git/parse` | URL-Zerlegung für https, SSH, verschachtelte GitLab-Gruppen und Oberflächenpfade; Provider-Erkennung; Bildung der Aktivitätskurve | +| `security/ssrf` | Sperrlisten für Loopback, Link-Local, Metadaten-Endpunkt, CGNAT und Multicast; Formprüfung; die drei Umgebungsschalter | +| `auth/password` | scrypt-Rundlauf, unterschiedliches Salz, Ablageformat, Verhalten bei kaputten Hashes, Passwortregeln | + +Bewusst ohne Datenbank- und Browsertests: die brauchen Infrastruktur und gehören in eine +CI-Pipeline. Das steht in der [ROADMAP](ROADMAP.md). + +### 6.5 API Zehn REST-Endpunkte für Projekte, Notizen, Verbindungen, Sync, Repo-Listen und Health. Alles, was die Oberfläche kann, ist damit auch scriptbar. Übersicht in der diff --git a/README.md b/README.md index be0233e..31c8cf9 100644 --- a/README.md +++ b/README.md @@ -298,6 +298,8 @@ nebula/ | `npm run db:seed` | Beispielprojekte anlegen | | `npm run db:studio` | Prisma Studio öffnen | | `npm run db:reset` | Datenbank zurücksetzen (**löscht alles**) | +| `npm test` | Unit-Tests (Vitest), unter einer Sekunde | +| `npm run test:watch` | Tests im Beobachtungsmodus | | `npm run typecheck` | TypeScript prüfen | | `npm run docker:db` | Nur die Datenbank starten | | `npm run docker:up` / `docker:down` | Kompletten Stack starten / stoppen | @@ -332,6 +334,7 @@ ausschließlich Daten des angemeldeten Kontos. | `GET` | `/api/projects/:id/export` | Ein Projekt (`?format=md` für Markdown) | | `POST` | `/api/projects/import` | Import, mit `dryRun` für die Vorschau | | `GET` | `/api/admin/backup` | Vollständige Sicherung als JSON (Admin) | +| `GET` | `/api/search?q=` | Volltextsuche über die eigenen Notizen | | `GET` `PATCH` `DELETE` | `/api/projects/:id` | Projekt lesen / ändern / löschen | | `POST` | `/api/projects/:id/sync` | Repo-Daten vom Git-System holen | | `GET` `POST` | `/api/projects/:id/notes` | Notizen des Projekts | diff --git a/ROADMAP.md b/ROADMAP.md index 44b596a..deab3b4 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -11,101 +11,74 @@ Was bereits steht, listet [FEATURES.md](FEATURES.md). ## 1 · Als Nächstes empfohlen -### 1.1 Markdown in Beschreibung und Notizen `S` +### 1.1 Tests ausbauen: Datenbank und Browser `L` -Heute wird alles als reiner Text dargestellt. Mit Markdown werden aus -`- [ ] Aufgabe` echte Checklisten, Codeblöcke bekommen Hervorhebung, Links -werden klickbar. +Das Fundament steht — 51 Unit-Tests der reinen Logik laufen in unter einer +Sekunde. Was fehlt, ist die Schicht darüber: -Zu beachten: HTML muss beim Rendern entfernt werden, sonst reißt es ein -XSS-Loch. Mit `react-markdown` plus `rehype-sanitize` ist das sauber lösbar. +- **Integrationstests** gegen eine Wegwerf-Datenbank: Datentrennung zwischen + Konten, Import-Strategien, Backoff des Abgleichs +- **Playwright** für die Wege durch die App: Einrichtung, Anmeldung, Kanban +- **CI-Pipeline** bei GitHub oder Gitea Actions -### 1.2 Volltextsuche über Notizen `S` +Ich prüfe bislang alles von Hand, inklusive Screenshots. Das trägt nicht +dauerhaft und macht jede weitere Änderung teurer als nötig. -Die Suche im Board deckt Namen, Kurzbeschreibung und Tags ab — Notizen nicht. -Postgres kann das nativ (`tsvector` mit deutscher Konfiguration), also ohne -zusätzlichen Dienst. +### 1.2 Benachrichtigungen `M` -### 1.3 Kanban-Board mit Drag & Drop `M` +Bei Sync-Fehlern, roter CI, neuen Releases oder Projekten, die lange +stillstehen. Kanäle: E-Mail (SMTP), ntfy, generischer Webhook. Zusammen mit +dem automatischen Abgleich und dem CI-Status ergibt das ein brauchbares +Frühwarnsystem — die Daten liegen bereits vor. -Die gruppierte Ansicht gibt es schon, aber Statuswechsel geht nur über das -Menü. Spalten mit Ziehen und Ablegen wären der natürlichere Weg. +### 1.3 Aufgaben und Checklisten `M` -Bibliothek: `@dnd-kit` — leichtgewichtig, tastaturbedienbar. Auf Mobilgeräten -bleibt die Listenansicht. +Eigene Entität statt Freitext, mit Häkchen und automatisch berechnetem +Fortschritt. Ersetzt das manuelle Schieben des Reglers. Die Markdown- +Checklisten in Notizen sind ein Vorgeschmack, aber nicht auswertbar. --- ## 2 · Danach -### 2.1 Offene Pull Requests und Issues als Liste `S` - -Aktuell werden sie nur gezählt. Titel, Autor, Alter und Link wären deutlich -nützlicher — die Daten holen wir ohnehin schon ab. - -### 2.2 CI-Status je Branch `M` - -Grün oder rot direkt an der Projektkarte, gespeist aus GitHub Actions, -GitLab Pipelines und Gitea Actions. Erfordert je Provider einen weiteren -Endpunkt und einen zusätzlichen Token-Scope. - -### 2.3 Webhooks statt Polling `M` +### 2.1 Webhooks statt Polling `M` Ein Push aktualisiert den Snapshot sofort, statt bis zum nächsten Durchlauf zu warten. Braucht einen öffentlich erreichbaren Endpunkt mit Signaturprüfung je Provider — sinnvoll erst, wenn die Instanz von außen erreichbar ist. Der Zeitplan bleibt als Rückfalllösung. -### 2.4 Commit-Aktivität als Verlauf `S` +### 2.2 Commit-Aktivität als Heatmap `S` -Kleine Sparkline auf der Karte, Heatmap auf der Projektseite. Datenbasis ist -da, es fehlt nur die Darstellung. +Die Sparkline gibt es auf Karte und Projektseite. Eine Heatmap über ein Jahr +wäre die nächste Ausbaustufe — dafür braucht es allerdings mehr als eine +Seite Commits, also Paginierung oder die Statistik-Endpunkte. -### 2.5 Aufgaben und Checklisten `M` +### 2.3 Kanban mit freier Reihenfolge `M` -Eigene Entität statt Freitext-Notiz, mit Häkchen und automatisch -berechnetem Fortschritt. Ersetzt das manuelle Schieben des Reglers. - -### 2.6 Benachrichtigungen `M` - -Bei Sync-Fehlern, neuen Releases oder Projekten, die lange stillstehen. -Kanäle: E-Mail (SMTP), ntfy, generischer Webhook. Zusammen mit dem -automatischen Abgleich ergibt das ein brauchbares Frühwarnsystem. +Heute folgt die Reihenfolge innerhalb einer Spalte der gewählten Sortierung. +Frei sortieren hieße, eine Position je Projekt zu speichern. --- ## 3 · Größere Brocken -### 3.1 Automatisierte Tests und CI `L` - -Aktuell prüfe ich jede Änderung von Hand — Typecheck, Build, API-Durchläufe, -Browser-Screenshots. Das gehört in eine Pipeline: - -- **Vitest** für die Logik: URL-Parsing, SSRF-Regeln, Passwort-Hashing, - Backoff-Berechnung -- **Playwright** für die Wege durch die App: Einrichtung, Anmeldung, - Datentrennung -- **GitHub Actions** oder Gitea Actions, je nachdem wohin du das Repo legst - -Aus meiner Sicht der wertvollste Punkt der ganzen Liste, sobald das Projekt -länger lebt: er macht alles Weitere billiger und sicherer. - -### 3.2 Mehrere Repositories je Projekt `M` +### 3.1 Mehrere Repositories je Projekt `M` Frontend und Backend getrennt, aber ein Projekt. Erfordert eine Zwischen­tabelle und Anpassungen in der Anzeige. -### 3.3 Zwei-Faktor per TOTP `M` +### 3.2 Zwei-Faktor per TOTP `M` Als Alternative zum Passkey — nützlich, wenn die Instanz aus dem Internet erreichbar ist und nicht jedes Gerät Passkeys kann. -### 3.4 Passwort-Zurücksetzen per E-Mail `M` +### 3.3 Passwort-Zurücksetzen per E-Mail `M` Heute setzt ein Administrator das Passwort neu. Selbstbedienung braucht SMTP und damit eine weitere Konfiguration — lohnt erst im Mehrbenutzerbetrieb. -### 3.5 Mehrsprachigkeit `L` +### 3.4 Mehrsprachigkeit `L` Die Oberfläche ist durchgängig deutsch verdrahtet. Englisch dazu wäre eine Voraussetzung, falls du das Projekt veröffentlichen willst. @@ -117,6 +90,7 @@ Voraussetzung, falls du das Projekt veröffentlichen willst. | Idee | Aufwand | Nutzen | | --- | --- | --- | | Schnellsuche per `Strg+K` | `S` | Springt direkt zu Projekt oder Aktion | +| Suchtreffer in Notizen hervorheben | `S` | In der Notiz selbst, nicht nur in der Trefferliste | | Mehrfachauswahl im Board | `S` | Status oder Tags für mehrere auf einmal | | Aktivitätsverlauf je Projekt | `S` | Wer hat wann was geändert | | Projektvorlagen | `S` | Neues Projekt mit vorgefüllten Tags und Notizen | @@ -124,7 +98,7 @@ Voraussetzung, falls du das Projekt veröffentlichen willst. | Eigenes Logo und Farbe | `S` | Ergänzt `APP_NAME` | | PWA-Manifest | `S` | Auf dem Handy als App installierbar | | Barrierefreiheits-Durchsicht | `M` | Fokusreihenfolge, Screenreader, Kontraste | -| `prisma.config.ts` | `S` | Beseitigt die Deprecation-Warnung vor Prisma 7 | +| `prisma.config.ts` | `S` | Beseitigt die Deprecation-Warnung vor Prisma 7. Achtung: danach lädt Prisma die `.env` nicht mehr von selbst | | Audit-Log für Adminaktionen | `M` | Nachvollziehbar, wer Konten geändert hat | --- @@ -156,6 +130,8 @@ Damit klar ist, was **nicht** kommt und warum: | Docker- und Standalone-Betrieb | ✓ | | Automatischer Abgleich mit Zeitplan | ✓ | | Export, Import und Sicherung | ✓ | +| **v0.3.0** Markdown, Volltextsuche über Notizen, PR- und Issue-Listen, Testfundament | ✓ | +| **v0.4.0** Kanban mit Drag & Drop, CI-Status je Branch, Commit-Aktivität | ✓ | Zur Entscheidung beim Export: Git-Tokens gehen **nicht** mit. Die Verbindung wird nur beschrieben, das Token ist nach dem Import neu zu hinterlegen. Snapshots bleiben