Komponenten-Release-Watch

Status: LIVE seit 2026-05-12 Konzept: Component-Release-Watch — Konzept

Was es ist

Eine zentrale Admin-Ansicht, die für alle externen Komponenten zeigt:

welche Versionen wo laufen,
welche neuen Releases es gibt,
was die neuen Versionen inhaltlich bringen (Features, Bugfixes, Deprecations),
ob deprecated Endpoints tatsächlich von Prilog-Code genutzt werden (Cross-Match),
wie wir uns entschieden haben (Annotation: relevant/in-use/geplant/ignoriert + Notiz).

Ziel: kein Synapse-Update, das uns überrascht. Vor jeder Tag-Bump-Entscheidung weiß ein Plattform-Admin, was kommt und was wir verlieren würden.

Wo finde ich das

Admin-Portal → Sidebar → Komponenten (Releases) URL: https://admin.prilog.chat/components

Welche Komponenten werden getrackt

Initial-Liste (alle in der component_definitions-Tabelle, idempotent geseeded):

Komponente	Quelle	Identifier
Synapse	GitHub Releases	`element-hq/synapse`
MinIO	GitHub Releases	`minio/minio`
n8n	GitHub Releases	`n8n-io/n8n`
faster-whisper	GitHub Releases	`SYSTRAN/faster-whisper`
Postgres	DockerHub Tags	`library/postgres` (Filter `\d+(\.\d+)?-alpine`)
matrix-js-sdk	NPM Registry	`matrix-js-sdk`
Prisma	NPM Registry	`prisma`
Fastify	NPM Registry	`fastify`
@tiptap/core	NPM Registry	`@tiptap/core`

Weitere Komponenten kommen via Datenbank-Eintrag dazu — kein Code-Deploy nötig. Siehe Abschnitt "Neue Komponente hinzufügen".

Was sieht man auf der Übersicht

Spalte	Bedeutung
Komponente	Display-Name + GitHub/NPM-Identifier
Typ	Container / NPM / Python
Laufende Version(en)	aktuell: aus Spec (Soll), Tenant-Manifeste (Ist), oder package.json
Neueste Release	jüngste nicht-prerelease Release in der DB
Status	offene Alerts (rot) · ungereviewte Releases (gelb) · aktuell (grün)
Zuletzt geprüft	letzter erfolgreicher Fetch

Pro Zeile zwei Aktionen: manueller Fetch (Refresh-Icon) und Detail-Klick.

Oben rechts ein Button "API-Inventar re-crawlen + Alerts neu berechnen" — scannt sofort Repos + Cross-Match. Sonst macht das ein Cron Mo 07:00 UTC.

Detail-Page (pro Komponente)

Zeigt drei Bereiche:

Releases-Liste chronologisch absteigend. Pro Release: Version, Datum, Counts (Features/Bugfixes/Deprecations/Upgrade-Notes/Security). Klick öffnet Drawer.
API-Usage-Aggregat — alle Endpoints dieser Komponente, die im Prilog-Code referenziert sind, mit Treffer-Anzahl und Anzahl betroffener Dateien.
Filter: Status-Dropdown (zeige nur "relevant", "in-use", "ignoriert" etc.) + Pre-Releases einblenden.

Release-Drawer

Klick auf eine Release öffnet rechts einen Drawer mit:

Version + Original-Link zu GitHub
Prilog-Annotation: Status-Dropdown + Notiz (Markdown), wird gespeichert mit evaluatedBy/evaluatedAt.
Alerts (falls vorhanden) — rote Box mit Cross-Match-Treffern.
Strukturierte Sections: Security · Deprecations · Upgrade-Notes · Features · Performance · Bugfixes · Internal · Other.

Jeder Bullet-Eintrag aus dem Changelog wird einzeln gelistet mit PR-Link, falls vorhanden.

Annotation-Status

Status	Bedeutung
`new`	Default — wurde noch nicht angeschaut
`reviewed`	Wurde angeschaut, keine Aktion nötig
`relevant`	Wir wollen das, müssen es noch umsetzen
`in_use`	Wir nutzen das schon
`planned`	Eingeplant für ein zukünftiges Release-Update
`ignored`	Bewusst nicht — Grund steht in Notiz

Der Status ist nicht semantisch wertend, sondern reine Workflow-Hilfe. Wir entscheiden, dokumentieren, gehen weiter.

Alerts — wann wird's rot?

Ein Alert entsteht, wenn ein Release in seiner Deprecations- oder Upgrade-Notes-Section einen Endpoint nennt, den Prilog tatsächlich im Code aufruft. Beispiel:

Synapse v1.155.0 — Deprecations: POST /_synapse/admin/v1/reset_password will be removed in v1.158.
↳ Prilog nutzt das in 4 Code-Stellen (customer/users.router.ts:1248, sync.router.ts:152, …).

Cross-Match-Logik:

Endpoint aus Markdown-Text per Regex extrahiert
Prefix-Match gegen component_api_usage.endpoint
Bei Treffer entsteht component_release_alerts-Eintrag.

Alerts sind acknowledgeable — ein Admin kann sie mit Begründung dismissen ("Wir migrieren mit dem Update").

Cron-Jobs

Job	Schedule	Was
`component-release-fetch`	Täglich 06:00 UTC	Holt alle enabled Definitions, GitHub-ETag-Cache wo möglich
`component-alert-recompute`	Täglich 08:00 UTC	Cross-Match Deprecations × Usage
`component-api-usage-crawl`	Montags 07:00 UTC	Re-crawl der Repos

Alle drei sichtbar unter Admin → Cron-Jobs.

Manueller Trigger

Wenn man nicht auf den Cron warten will:

Über die UI: Komponenten-Page, Refresh-Button pro Komponente oder Bulk-Button oben.

Über Backend-Endpoints:

bash

POST /api/admin/components/<component>/fetch
POST /api/admin/component-watch/recrawl

Über Script (auf api.prilog.chat):

bash

cd /var/www/backend-api
npx tsx scripts/fetch-component-releases.ts            # alle
npx tsx scripts/fetch-component-releases.ts synapse    # einzeln
npx tsx scripts/crawl-component-usage.ts               # API-Crawler

Neue Komponente hinzufügen

Zwei Wege:

Permanent (für alle Tenants/Deployments): Eintrag in src/services/component-watch/seed-definitions.ts ergänzen, Push, Server npx tsx scripts/seed-component-definitions.ts aufrufen.

Ad-hoc: Direkt in die DB einfügen (SQL oder Prisma Studio):

sql

INSERT INTO component_definitions
  (component, display_name, category, source_type, source_identifier, current_version_query, enabled, updated_at)
VALUES
  ('redis', 'Redis', 'container', 'github_release', 'redis/redis', 'static:7.4', true, NOW());

Beim nächsten Cron (oder manuellem Fetch) werden Releases gezogen.

Was passiert nicht (mit Absicht)

Kein Auto-Update. Wir benachrichtigen, schlagen vor, dokumentieren. Der Tenant-Box-Reconcile macht eigenständige Versions-Bumps nur wenn Plattform-Admin die Spec hochsetzt.
Kein automatisches "wir migrieren euch"-Skript. Update-Entscheidungen sind manuell, je Komponente.
Kein Pull-Request-Generator (Dependabot-artig). NPM-Bumps machen wir bewusst, mit Sicht auf das Drumherum.

Architektur-Diagramm

                  ┌──────────────────┐
                  │  Cron 06:00 UTC  │
                  └────────┬─────────┘
                           │
              ┌────────────▼────────────┐
              │   fetcher.service.ts    │ ── per-Komponente
              └────────────┬────────────┘
                           │
                 ┌─────────▼──────────┐
                 │   Adapter-Layer    │
                 │  ┌──────────────┐  │
                 │  │GitHub Release│  │
                 │  │DockerHub Tag │  │
                 │  │NPM Registry  │  │
                 │  └──────────────┘  │
                 └─────────┬──────────┘
                           │
              ┌────────────▼─────────────┐
              │  changelog-parser.ts     │  Markdown → bodyStructured
              └────────────┬─────────────┘
                           │
                  ┌────────▼────────┐
                  │ component_      │
                  │   releases      │  ← Upsert
                  └────────┬────────┘
                           │
       ┌───────────────────┴───────────────────┐
       │  Cron 08:00 UTC: alert-computer.ts    │
       │  Cross-Match Deprecations × Usage      │
       └───────────────────┬───────────────────┘
                           │
                  ┌────────▼────────┐
                  │ component_      │
                  │   release_alerts│
                  └─────────────────┘

       ┌──────────────────────────────────────┐
       │   Cron Mo 07:00 UTC: usage-crawler   │
       │   grep'd unsere Repos                 │
       └───────────────────┬──────────────────┘
                           │
                  ┌────────▼────────┐
                  │ component_      │
                  │   api_usage     │
                  └─────────────────┘

Workflow für Plattform-Admin

Wochen-Check (Montag morgen): Admin-Page öffnen, "ungereviewte Releases" anschauen.
Bei jeder Release: Drawer öffnen, Changelog überfliegen, Status setzen + Notiz.
Wenn Alert auftaucht: Endpoint-Liste prüfen, entscheiden ob (a) Code anpassen vor Update oder (b) Acknowledge mit Begründung.
Bei Versions-Bump: Spec hochsetzen + Reconcile triggern → Tenants ziehen nach.
Quartals-Check: Liste mit prilog_status='relevant' und Status != in_use durchgehen — was haben wir versäumt zu implementieren.

Stolpersteine

GitHub-Rate-Limit: ohne Token nur 60 req/h pro IP. Mit GITHUB_RELEASE_WATCH_TOKEN (env-var) → 5000/h. Pro Komponente macht der Fetcher 1 Request — mit 9 Komponenten reicht das selbst ohne Token, mit ETag-Cache bleibt es 0 Requests bei keinem neuen Release.
NPM-Bodies sind leer: NPM-Registry liefert keine Changelog-Bodies, nur Versions-Metadata. Wir markieren deprecated-Versionen über das NPM-Feld, sonst muss man bei NPM-Komponenten auf den GitHub-Repo-Link gehen.
DockerHub hat keine Releases: wir tracken Tags. Für Postgres bedeutet das, dass wir nur Versions-Sprünge sehen, keine echten Release-Notes. Verlinkung auf postgresql.org-Release-Notes ist Phase 2.
API-Usage hat False-Positives: Regex matchen alles was wie /_matrix/... aussieht. Files im component-watch/-Pfad sind ausgeschlossen, sonst zählt unser eigener Regex-String mit.

Datenbank-Tabellen

component_definitions — was wird getrackt
component_releases — Release-Cache (Body + Annotation)
component_api_usage — wo nutzen wir was im Code
component_release_alerts — berechnete Cross-Match-Treffer

Migration: 0073_component_release_watch.

Komponenten-Release-Watch ​

Was es ist ​

Wo finde ich das ​

Welche Komponenten werden getrackt ​

Was sieht man auf der Übersicht ​

Detail-Page (pro Komponente) ​

Release-Drawer ​

Annotation-Status ​

Alerts — wann wird's rot? ​

Cron-Jobs ​

Manueller Trigger ​

Neue Komponente hinzufügen ​

Was passiert nicht (mit Absicht) ​

Architektur-Diagramm ​

Workflow für Plattform-Admin ​

Stolpersteine ​

Datenbank-Tabellen ​