# GitCover.WebStaticBuilder

> **Version: 1.0.0** — Diese Versionsnummer steht in `README.md` (kanonisch),
> in `GitCover.WebStaticBuilder.csproj` (`<Version>`) und wird von `webstatic --version`
> ausgegeben. Alle drei Quellen müssen synchron gehalten werden.

Eigenständiger, quelloffener **Static-Site-Generator** der GitCover Commons für
mehrsprachige, SEO-optimierte, compliance-freundliche Websites. Ersetzt den
früheren C#-Builderskript der GCBoK-Website durch ein generisches, für KMU
einsetzbares Werkzeug.

- **Sprache:** C# / .NET 10 (kompilierte Konsole)
- **Lizenz:** MIT (siehe `LICENSE` für Third-Party-Dependency-Lizenzen)
- **Kein Python:** einzige externe Abhängigkeit ist `npx pagefind` (Suchindex, optional)
- **Funktionen:** Markdown + YAML-Frontmatter → statisches HTML pro Sprache,
  Navigation, SEO-Kopf (OpenGraph/JSON-LD), `sitemap.xml`, `robots.txt`,
  Mermaid-Diagramme, client-seitige Volltextsuche (Pagefind), UI-Lokalisierung
  über `{{ i18n.* }}`, optionaler Machine-Translation-Helfer (Entwürfe),
  Markdown-Rendering im Terminal via `webstatic status`.

## Schnellstart

```bash
# Tool bauen
dotnet build -c Release

# Beispiel-Seite erzeugen und bauen
dotnet bin/Release/net10.0/webstatic.dll init mysite
cd mysite
dotnet ../../bin/Release/net10.0/webstatic.dll build --env development

# Lokal ansehen
dotnet ../../bin/Release/net10.0/webstatic.dll serve --port 8000

# Site-Status (README.md im Terminal rendern)
dotnet ../../bin/Release/net10.0/webstatic.dll status
```

## CLI-Befehle

| Befehl | Bedeutung |
|--------|-----------|
| `webstatic build [Optionen]` | Website bauen |
| `webstatic serve [--port N]` | Lokalen Server starten (Vorschau) |
| `webstatic init <name>` | Beispiel-Site anlegen |
| `webstatic status [--root DIR]` | README.md der Site im Terminal anzeigen |
| `webstatic translate --check` | Fehlende Übersetzungen melden |
| `webstatic translate --draft` | Übersetzungs-Entwürfe erzeugen |
| `webstatic --version` | Version (Assembly + Git-Commit) anzeigen |
| `webstatic --help \| -h` | Hilfe anzeigen |
| `webstatic update` | Selbstaktualisierung (Clone-Installation) |

## Umgebungen

| `--env`      | baseUrl (Beispiel)           | Zweck                  |
|--------------|------------------------------|------------------------|
| `development`| `http://localhost:8000`      | Lokale Entwicklung (work/preview/review) |
| `staging`    | `https://gcbok.gitcover.org` | Abnahme (brx5)         |
| `deploy`     | `https://gcbok.org`          | Production             |

Aliase: `--preview` / `--work` / `--review` = `development`, `--staging` = `staging`, `--deploy` = `deploy`.

## Konfiguration (`webstatic.json`)

CLI-Flags haben Vorrang vor `webstatic.json`, dieses vor eingebauten Defaults.
Siehe `webstatic.example/webstatic.json` und `docs/getting-started.md`.

## Installation für KMU

```bash
./install.sh        # -> /opt/GitCover/webstatic, Symlink /usr/local/bin/webstatic
```

## Version & Update

Die Versionsnummer wird an drei Stellen synchron gehalten (Definition of Done
für jeden Release-Commit):

1. **`README.md`** — Block-Quote direkt unter dem Titel (kanonisch, per Remote
   via `git show origin/main:README.md` sichtbar)
2. **`GitCover.WebStaticBuilder.csproj`** — `<Version>1.0.0</Version>` (Assembly)
3. **`webstatic --version`** — gibt die Assembly-Version aus

So kann vor einem Update sowohl lokal (im Installations-Repo) als auch remote
(im Upstream-Repo) die Version festgestellt werden, ohne die CLI aufzurufen:

```bash
# Lokal installierte Version (Clone-Installation)
git -C /opt/GitCover/webstatic show HEAD:README.md | head -3

# Remote verfügbare Version (vor Pull)
git -C /opt/GitCover/webstatic show origin/main:README.md | head -3
```

### Update-Check via CLI

`webstatic --version` führt automatisch einen Remote-Check durch
(`git ls-remote origin HEAD`) und vergleicht lokalen mit remote Commit-Hash:

```bash
webstatic --version
# GitCover.WebStaticBuilder 1.0.0.0
# commit:  6ca8167 (local)
# remote:  ff634a3
#
#   UPDATE AVAILABLE
#   Run: webstatic update
```

Bei Copy-Installationen (kein `.git`) entfällt der Remote-Check; das Tool weist
auf `./install.sh` als Update-Weg hin.

### Update durchführen

```bash
webstatic update      # Selbstaktualisierung (Clone-Installation): lokale
                      # Änderungen werden gestasht, git pull, gemerged, neu gebaut
```

`webstatic update` setzt eine Clone-Installation voraus (siehe `install.sh`,
Default `WEBSTATIC_INSTALL_MODE=clone`). Bei einer Copy-Installation erfolgt das
Update via erneutem `./install.sh`.

## Machine Translation (optional)

```bash
webstatic translate --check                 # fehlende Übersetzungen melden
export WEBSTATIC_TRANSLATOR_KEY=...         # API-Key (Azure/DeepL)
webstatic translate --draft                 # Entwürfe nach .translation-drafts/
```

Entwürfe überschreiben niemals Quelldateien.

## Verzeichnisstruktur

```
plans/      Produktplan & Folgepläne
docs/       Anleitungen (KMU, Admin)
diary/      Entwicklungs-Tagebuch
src/        C#-Quellcode (GitCover.WebStaticBuilder)
tests/      (künftig) Unit/Integrationstests
webstatic.example/  Vorlage-Site für KMU
install.sh  KMU-Installation
LICENSE     MIT + Third-Party-Dependency-Lizenzen
```