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:
   ```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
```