build_webstatic/plans/01-offensichtliche-fixes.md

Plan 01 — Offensichtliche Fixes

Status: Draft (2026-07-11). Aus der Code-Inspektion und Testläufen gegen das GCBoK-Website-Repo (/mnt/brx5/REPOS/GCC/gcbok.gitcover.org) und das Dev-Quell-Repo (/mnt/brx5/work/OSS/build_webstatic) abgeleitet.

Kontext

Die GCBoK-Website nutzt jetzt ausschließlich die webstatic-CLI (alte www/build.py, www/build.sh und www/oss/-Vendor-Snapshot wurden entfernt). Dabei zeigten sich Probleme, die hier zur Behebung anstehen.

Fix 1 — Installierte Binary ist veraltet (/opt/GitCover/webstatic)

Symptom: webstatic --version und webstatic --help crashen mit DirectoryNotFoundException: .../content — der Build läuft los, bevor --help/--version ausgewertet werden.

Ursache: /opt/GitCover/webstatic/src/Program.cs (7223 B, 11. Jul 15:59) ist älter als der aktuelle Dev-Stand (src/Program.cs, 380 Zeilen). Die installierte Binary wurde aus einem Zwischenstand gebaut, in dem --help/--version-Checks erst nach Builder.Build() kamen. Der aktuelle Dev-Stand hat die Checks bereits an richtiger Position (Zeile 50–64, vor dem Build-Aufruf Zeile 118).

Maßnahme:

1. Dev-Quellbaum baut sauber (dotnet build -c Release ✓ verifiziert).
2. System-Installation aktualisieren:

   sudo env PATH="$PATH" \
     WEBSTATIC_INSTALL_DIR=/opt/GitCover/webstatic \
     WEBSTATIC_BIN_DIR=/usr/local/bin \
     /mnt/brx5/work/OSS/build_webstatic/install.sh
   

   (oder webstatic update, falls die Installation ein Clone ist — /opt/GitCover/webstatic/.git prüfen).
3. Verifizieren: webstatic --version (erwartet: 1.0.0.0 + Commit-Hash), webstatic --help (erwartet: Hilfe-Text, Exit 0), webstatic build --root /mnt/brx5/REPOS/GCC/gcbok.gitcover.org/www --env development --verbose (erwartet: erfolgreicher Build, Exit 0).

Fix 2 — --help/--version sollten VOR Config-Laden und Directories.Init geprüft werden

Symptom: Aktuell läuft BuildConfig.Load() (Zeile 24) und Directories.Init() (Zeile 47), bevor --help/--version abgefragt werden (Zeile 50/57). Das funktioniert zwar (Load ist fehlertolerant), ist aber fragil und verschwendet Arbeit.

Maßnahme: In src/Program.cs die --help/-h/help/--version-Checks ganz an den Anfang der Main verschieben (direkt nach den Hilfsfunktionen Has/Val, vor BuildConfig.Load).

Fix 3 — Fehlendes content/-Verzeichnis nicht graceful behandelt

Symptom: Wenn --root auf ein Verzeichnis ohne content/ zeigt (z. B. Repo-Root statt www/), crasht ContentLoader.LoadContent (Zeile 22: Directory.GetFiles(contentDir, ...)) mit ungefangenem DirectoryNotFoundException.

Maßnahme: In Builder.Build() (oder ContentLoader.LoadContent) prüfen, ob Directories.ContentDir existiert. Wenn nicht: klare Fehlermeldung

ERROR: content directory not found: <path>
       Specify --root <dir> or --content <dir>.

und return (Exit 1), statt Exception-Stacktrace.

Fix 4 — webstatic.example/ enthält Build-Artefakte im Git

Symptom: git ls-files webstatic.example/ zeigt build_log.txt, run_log.txt und das komplette dist/-Verzeichnis (HTML, Pagefind-Index) sind versioniert. Diese werden bei webstatic init mitkopiert.

Maßnahme:

1. webstatic.example/build_log.txt, webstatic.example/run_log.txt aus Git entfernen (git rm).
2. webstatic.example/dist/ aus Git entfernen (git rm -r).
3. .gitignore erweitern:

   webstatic.example/dist/
   webstatic.example/build_log.txt
   webstatic.example/run_log.txt
   

4. Sicherstellen, dass webstatic init die Beispiel-Site sauber scaffoldet (ohne Artefakte).

Fix 5 — Repo-eigene build_log.txt/run_log.txt werden beim Dev-Build geschrieben

Symptom: Ein Build im Dev-Quellbaum (z. B. dotnet ... build --root webstatic.example) schreibt build_log.txt und run_log.txt in den Build-Root (webstatic.example/). Das ist korrekt. Zusätzlich stehen aber build_log.txt und run_log.txt im Repo-Root (/mnt/brx5/work/OSS/build_webstatic/) und sind versioniert — sie werden bei jedem versehentlichen Build ohne --root (Default = cwd = Repo-Root) überschrieben.

Maßnahme:

1. build_log.txt und run_log.txt im Repo-Root aus Git entfernen (git rm).
2. In .gitignore aufnehmen:

   /build_log.txt
   /run_log.txt
   

3. (Optional) Guard im Code: wenn kein Subcommand und keine Build-Flags gegeben sind, Hilfe ausgeben statt blind zu bauen (verhindert versehentliche Builds im falschen Verzeichnis).

Fix 6 — BuildConfig.Defaults()-Umgebungen inkonsistent mit CLI-Aliasen

Symptom: BuildConfig.Defaults() (Zeile 82–88) definiert work und review als eigene Umgebungen. Die CLI mappt --work/--review aber auf development (Program.cs:103–105). Wenn ein Nutzer --env work direkt aufruft, bekommt er die Default-work-Umgebung (mit BaseUrl=http://localhost:8000), während --work auf development mappt. Da webstatic.json die Environments überschreibt, betrifft das nur Sites ohne eigene Config.

Maßnahme: BuildConfig.Defaults() bereinigen: work/review entfernen oder durch development ersetzen, so dass Defaults und CLI-Aliase konsistent sind. Dokumentation in plans/00 und README anpassen.

Fix 7 — tests/ ist leer

Symptom: tests/-Verzeichnis existiert, ist aber leer. Keine Unit-/Integrationstests vorhanden.

Maßnahme: (nicht Teil dieses Plans — separater Plan für Test-Aufbau). Vorläufig: tests/README.md anlegen, das den Platzhalter erklärt und auf den künftigen Test-Plan verweist.

Priorisierung

Fix	Priorität	Aufwand	Risiko
1 — Installierte Binary aktualisieren	hoch	gering	gering
3 — Content-Verzeichnis-Check	hoch	gering	gering
4 — Example-Artefakte aus Git	hoch	gering	gering
5 — Repo-Root-Logs aus Git	mittel	gering	gering
2 — Help/Version frühe Prüfung	mittel	gering	gering
6 — Default-Environments bereinigen	mittel	gering	gering
7 — tests/ Platzhalter	niedrig	trivial	—

Verifizierung nach allen Fixes

cd /mnt/brx5/work/OSS/build_webstatic
dotnet build -c Release
dotnet bin/Release/net10.0/webstatic.dll --version          # Exit 0
dotnet bin/Release/net10.0/webstatic.dll --help             # Exit 0
dotnet bin/Release/net10.0/webstatic.dll build --root .     # klare Fehlermeldung, Exit 1
dotnet bin/Release/net10.0/webstatic.dll build --root webstatic.example --env development  # Exit 0
git status                                                   # keine Artefakte, clean
# System-Install aktualisieren und GCBoK bauen:
sudo env PATH="$PATH" WEBSTATIC_INSTALL_DIR=/opt/GitCover/webstatic \
  WEBSTATIC_BIN_DIR=/usr/local/bin ./install.sh
webstatic --version
webstatic build --root /mnt/brx5/REPOS/GCC/gcbok.gitcover.org/www --env development --verbose