CLI-Fixes: Help/Version vor Build, Content-Check, Default-Envs, Artefakte aus Git

- Program.cs: --help/--version werden vor Config-Laden und
  Directories.Init geprüft (verhindert Crashes außerhalb eines
  Site-Verzeichnisses)
- Builder.cs: Pre-flight-Check ob content/ existiert; bei Fehlen
  klare Fehlermeldung + Exit 1 statt unhandled Exception.
  Build() gibt bool zurück, Program.cs setzt Environment.ExitCode.
- BuildConfig.cs: Default-Environments von work/review/staging/deploy
  auf development/staging/deploy bereinigt (konsistent mit CLI-Aliasen)
- .gitignore: build_log.txt/run_log.txt und webstatic.example/dist/
  ignoriert; entsprechende Artefakte aus Git entfernt
- tests/README.md: Platzhalter für künftige Test-Strategie
- plans/01-offensichtliche-fixes.md: Fix-Plan dokumentiert

plans/01-offensichtliche-fixes.md

@@ -0,0 +1,158 @@
+# 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:
+   ```bash
+   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
+
+```bash
+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
+```