build_webstatic/plans/01-offensichtliche-fixes.md

Plan 01 — Offensichtliche Fixes

Status: Größtenteils umgesetzt (Stand 2026-07-12). Die meisten Fixes sind bereits im Code landen (Commits 18c2108 CLI-Fixes, 7065c07 Link-Fixes u. a.). Fix 1 ist gegenstandslos (keine /opt-Installation vorhanden).

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)

Status: gegenstandslos (2026-07-12). Es existiert keine Installation unter /opt/GitCover/webstatic. Die aktiv genutzte Installation ist die per-user Betatester-Install unter ~/.local/share/GitCover/webstatic (Launcher ~/.local/bin/webstatic, Commit 7065c07). Ein Remote-Stand (89f720a) ist verfügbar → Aktualisierung via webstatic update.

Das ursprüngliche Symptom (Crash von --help/--version wegen fehlender content/-Prüfung) ist ohnehin bereits behoben (Commit 18c2108: „CLI-Fixes: Help/Version vor Build, Content-Check, Default-Envs, Artefakte aus Git"). webstatic --version liefert 1.0.0.0 + Commit-Hash (Exit 0).

Maßnahme (falls dennoch eine System-Installation gewünscht):

sudo env PATH="$PATH" WEBSTATIC_INSTALL_DIR=/opt/GitCover/webstatic \
  WEBSTATIC_BIN_DIR=/usr/local/bin ./install.sh

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
# Per-user-Install aktualisieren und GCBoK bauen:
cd ~/.local/share/GitCover/webstatic && git stash && git pull && ./install.sh
webstatic --version
webstatic build --root /mnt/brx5/REPOS/GCC/gcbok.gitcover.org/www --env development --verbose
webstatic build --root /mnt/brx5/REPOS/GCC/gcc.gitcover.org/www --env development --verbose