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):**
```bash
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

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