Separation as Tool

2026-07-11 13:43:52 +02:00
commit f542382e58
80 changed files with 5863 additions and 0 deletions
@@ -0,0 +1,99 @@
+# GCBoK.WebStaticBuilder — Produktbeschreibung & Umsetzungsplan
+
+> Status: Implementierung (Phase 1 abgeschlossen, Build verifiziert). Eigenständiges OSS-Static-Site-Tool der GitCover Commons.
+> Lizenz: MIT. Sprachen: C# / .NET 10 (keine Python-Abhängigkeiten).
+
+## 1. Zweck
+`GCBoK.WebStaticBuilder` (CLI-Befehl `webstatic`) ist ein schlanker, kompilierter Static-Site-Generator für mehrsprachige, SEO-optimierte, compliance-freundliche Websites. Er liest Markdown-Quellen mit YAML-Frontmatter, rendert sie pro Sprache zu statischem HTML, erzeugt Navigation, SEO-Kopf (OpenGraph/JSON-LD), Sitemap, robots.txt und einen client-seitigen Volltextindex (Pagefind) — ohne Server, Datenbank oder Build-Service.
+
+Das Tool ist die Verallgemeinerung des Builders, der die GCBoK-Website erzeugt, und soll es insbesondere **KMU-Anwendern** ermöglichen, eigene Websites nach derselben Funktionsweise zu erstellen.
+
+## 2. Zielgruppe
+- **Primär:** KMU, die eine mehrsprachige, datenschutzfreundliche, revisionssichere Website/ Dokumentation betreiben wollen (kein JS-Framework, kein Tracking, statisch hostbar).
+- **Sekundär:** OSS-Projekte, Behörden, gemeinnützige Träger mit BoK-/Compliance-Anspruch.
+
+## 3. Architektur & Technik
+- **C# / .NET 10**, kompilierte Konsolen-App (`OutputType Exe`), Ziel-Framework `net10.0`, Assembly `webstatic`.
+- **NuGet (alle MIT/BSD-2, lizenzkonform):** `Markdig` (BSD-2), `YamlDotNet` (MIT). Machine-Translation nutzt `System.Net.Http` (kein Extra-Paket).
+- **Kein Python.** Einziger externer Build-Schritt: `npx pagefind` (Node, best-effort, per Config abschaltbar).
+- Modulare `src/`-Struktur: `BuildConfig`, `Directories`, `Model`, `ContentLoader`, `MarkdownProcessor`, `SeoHelper`, `I18n`, `Builder`, `Translation/*`.
+
+## 4. Funktionsumfang
+- Markdown + YAML-Frontmatter → statisches HTML pro Sprache (eigener Ordner je Sprache).
+- Automatische Navigation (`.md`-Reihenfolge via `order`/`section`), Sidebar-TOC, Prev/Next.
+- SEO: `<title>`, Description, Canonical, OpenGraph, Twitter-Card, **JSON-LD**; `sitemap.xml`, `robots.txt`.
+- Mermaid-Diagramme (CDN, saubere einmalige Initialisierung), responsives Layout.
+- **Client-Suche:** Pagefind-Index im Post-Build (Mehrsprachigkeit via `<html lang>`).
+- **i18n:** UI-Chrome (Nav/Footer/ARIA/Sprachumschalter) mehrsprachig über `I18n.cs` + `{{ i18n.* }}`-Platzhalter.
+- **MT-Helfer:** `translate --check` meldet fehlende Übersetzungen; `translate --draft` erzeugt Entwürfe (nie auto-überschreiben).
+- **Umgebungen:** deklarativ in Config, wählbar via `--env`.
+
+## 5. Mehrsprachigkeit
+- Inhalte: pro Sprache eigene Datei (`<basis>.<lang>.md`), Fallback-Logik.
+- UI-Strings: portiertes `i18n.py`-Wörterbuch nach `I18n.cs` (de/en/vi), zur Laufzeit pro Sprache injiziert.
+- Kultur-korrekte Datums-/Zahlformate über `System.Globalization` (vorbereitet).
+- Optional: MT-Provider (Azure/DeepL) erzeugt **Entwürfe** für fehlende Inhaltsübersetzungen (klar markiert, separater Ordner `.translation-drafts/`).
+
+## 6. Umgebungen (Arbeitsumgebung / Review / Staging / Public Deployment)
+| Umgebung | `--env` | baseUrl (Beispiel) | cdn | Zweck / Ort |
+|---|---|---|---|---|
+| **Arbeitsumgebung** | `work` (`--preview`) | `http://localhost:8000` | `/assets` | Lokale Entwicklung; Build→lokales `dist/`, Vorschau via `serve` |
+| **Review** | `review` | `https://review.gitcover.org` | CDN | Freigabe/Vorschau (Konzept) |
+| **Staging** | `staging` | `https://gcbok.gitcover.org` | `https://gitcover.org/assets` | Abnahme (brx5 `/var/www/gcbok.gitcover.org`) |
+| **Public Deployment** | `deploy` | `https://gcbok.org` | `https://gitcover.org/assets` | Production (manueller Upload WebFTP) |
+
+## 7. CLI-Referenz
+```
+webstatic build --env <work|review|staging|deploy> [--content DIR] [--templates DIR]
+                [--assets DIR] [--output DIR] [--base-url URL] [--cdn PATH]
+                [--langs de,en,vi] [--default-lang de] [--config FILE] [--root DIR]
+                [--verbose] [--dry-run]
+webstatic translate --check            # fehlende Übersetzungen melden
+webstatic translate --draft            # Entwürfe erzeugen (MT, API-Key nötig)
+webstatic init <sitename>              # KMU-Onboarding: Site scaffolden
+webstatic serve [--port 8000]          # lokale Vorschau (.NET HttpListener)
+```
+Aliase `--preview`=`work`, `--staging`=`staging`, `--deploy`=`deploy` bleiben erhalten.
+
+## 8. Konfiguration (`webstatic.json`)
+- `site` (name/title/description je Sprache), `default_language`, `languages` (name/og_locale/href_lang/label), `paths` (content/templates/assets/output/legal/i18n), `glossary_section` + `glossary.href/label`, `pagefind` (bool), `translator` (provider/key_env/endpoint/region), `environments` (work/review/staging/deploy mit base_url/cdn).
+- Priorität: CLI-Flags > `webstatic.json` > eingebaute Defaults.
+
+## 9. Installation für KMU (`install.sh`)
+- Bash-Skript (kein Python): prüft .NET 10, `dotnet build -c Release`, kopiert nach **`/opt/GitCover/webstatic`**, Symlink `webstatic`→App nach `/usr/local/bin`, setzt `WEBSTATIC_BUILDER`.
+- Idempotent; meldet Voraussetzungen.
+
+## 10. Onboarding-Flow für KMU
+- `webstatic init <sitename>` scaffolder: kopiert `webstatic.example/` (content/templates/assets + Config), fragt Sprachen/Site-Titel.
+- `webstatic serve` (lokale Vorschau) und `webstatic build --env staging` als Kern.
+- Review-Gate/Konzept (Assistent, Freigabe) wird separat finalisiert.
+
+## 11. Repository-Struktur (Ziel)
+```
+build_webstatic/
+  plans/      # dieser Plan + Folgepläne
+  docs/       # Anleitungen (KMU, Admin)
+  diary/      # Entwicklungs-Tagebuch / Changelog
+  src/        # C#-Quellcode (GCBoK.WebStaticBuilder)
+  tests/      # (künftig) Unit/Integrationstests
+  webstatic.example/  # Vorlage-Site für KMU
+  install.sh  README.md  LICENSE (MIT)  AGENTS.md  MEMORY.md  SKILLS.md
+```
+
+## 12. Lizenz & Compliance
+- Code: **MIT** (`LICENSE`). Kompatibel mit allen genutzten NuGet-Paketen.
+- Inhalte der GCBoK-Site: separat (angestrebt CC BY-SA 4.0) — betrifft das Tool nicht.
+
+## 13. Umsetzungsphasen
+- **Phase 0 — Dev-Setup:** `build_webstatic` auf `/mnt/brx5/work/OSS/build_webstatic` (kopiert aus `www/build`, Python/`build.csx` entfernt, Verzeichnisstruktur plans/docs/diary/src/tests).
+- **Phase 1 — Refactor (DONE):** Umbenennung `GCBoK.WebStaticBuilder`; Python entfernt; Config/Umgebungsmodell; i18n (`I18n.cs` + Platzhalter); MT-Helfer; Pagefind; `webstatic.example`; `install.sh`; Docs/LIZENZ. Build & Verify auf Beispielsite ✓.
+- **Phase 2 — Install & Verify:** `install.sh` → `/opt/GitCover/webstatic`; Standalone-Smoke-Test.
+- **Phase 3 — Website-Repo:** Submodul `www/build` entfernen; `www/build.sh` durch Bash ersetzen; alle Docs (AGENTS/MEMORY/SKILLS/CONTEXT/README/docs/DEPLOYMENT/oss/*/.hermes) auf neuen Pfad/Tool/Umgebungen/kein-Python aktualisieren; GCBoK-Preview-Build + Dead-Link-Check.
+- **Phase 4 — Onboarding:** `init`/`serve`/`build` als KMU-Flow (Konzept finalisieren).
+- **Phase 5 — Abschluss:** Zusammenfassung; Commit/Signierung nur auf Wunsch.
+
+## 14. Offen / Risiken
+- **Review-Umgebung:** Konzept (Host/Subdomain/Freigabe) noch offen.
+- **MT-Sicherheit:** Entwürfe nur als Draft, nie auto-übernommen.
+- **Rückwärtskompat GCBoK:** Config-Defaults spiegeln GCBoK-Struktur.
+- **Portabilität:** `/opt` maschinenspezifisch → `WEBSTATIC_BUILDER` + `install.sh` dokumentiert.