1. Installation & Setup

Willkommen bei MeinCMS (wissen-ahrensburg.de). Dieses Kapitel führt dich Schritt für Schritt durch die Vorbereitung der Systemumgebung, das Klonen, das Kompilieren sowie die initiale Einrichtung der Datenbank und des Administrator-Accounts.

📋 Systemvoraussetzungen

Stelle sicher, dass folgende Softwarekomponenten auf deinem Linux-System installiert sind:

• Rust & Cargo: Version 1.80 oder neuer (rustup.rs)
• PostgreSQL: Version 14 oder neuer
• Git: Zum Klonen des Quellcodes
• (Optional) Nginx oder Caddy: Als Reverse Proxy für TLS/HTTPS im Produktionsbetrieb.

1. Repository klonen

Klone das Repository auf deinen Zielserver:

git clone https://github.com/thorstenkloehn/wissen-ahrensburg.de.git
cd wissen-ahrensburg.de

2. PostgreSQL Datenbank einrichten

MeinCMS benötigt eine PostgreSQL-Datenbank. Erstelle eine neue Datenbank und einen Datenbank-Benutzer:

-- In psql (als postgres-User):
CREATE USER meincms WITH PASSWORD 'dein_sicheres_passwort';
CREATE DATABASE meincms OWNER meincms;
GRANT ALL PRIVILEGES ON DATABASE meincms TO meincms;

Setze anschließend die Umgebungsvariable DATABASE_URL:

# Option A: TCP Connection (Entwicklung)
export DATABASE_URL="postgres://meincms:dein_sicheres_passwort@localhost:5432/meincms"

# Option B: Unix Domain Socket (Produktions-Server)
export DATABASE_URL="postgres://meincms:dein_sicheres_passwort@/var/run/postgresql/meincms"

3. Projekt kompilieren (Build)

Der Rust Workspace besteht aus den vier Crates:

1. meincms_parser: Markdown & MediaWiki Compiler
2. meincms_web: Axum Webbackend
3. meincms_backup: Backup & Repair CLI
4. meincms_admin: Admin & Benutzer-Verwaltung

Entwicklungs-Build (Debugging)

cargo build

Produktions-Build (Optimiert)

Für maximale Performance kompiliere die Anwendung im Release-Modus:

cargo build --release

Die fertigen Binaries befinden sich anschließend unter target/release/.

4. Admin-Benutzer erstellen

Vor dem ersten Start solltest du deinen Administrator-Account anlegen. Nutze dafür das CLI-Tool meincms_admin:

cargo run -p meincms_admin -- create-user --username admin@wissen-ahrensburg.de

Das CLI-Tool fordert dich auf, ein sicheres Passwort einzugeben. Der Hash wird mittels Argon2id geschützt und in config/users.json gespeichert.

5. Webserver starten

Starte den Axum-Server mit:

# Entwicklungsmodus (TCP Port):
PORT=5000 cargo run -p meincms_web

# Produktionsmodus (Unix Domain Socket):
UNIX_SOCKET="/run/meincms/meincms.sock" ./target/release/meincms_web

Nach dem Start im TCP-Modus ist die Anwendung unter http://localhost:5000 erreichbar.

6. Nginx Reverse Proxy (Produktion)

Um die Anwendung im Produktivbetrieb mit HTTPS / Let's Encrypt über den Unix-Socket abzusichern:

server {
    listen 80;
    server_name wissen-ahrensburg.de;

    location / {
        proxy_pass http://unix:/run/meincms/meincms.sock;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

7. Dokumentation bauen & veröffentlichen (mdBook)

Die Handbuch-Dokumentation wird mit mdBook generiert und bindet automatisch AGENTS.md sowie alle Subagent-Skills ein.

• Dokumentation lokal bauen:

  npm run build:docs
  

  Synchronisiert .agents/AGENTS.md und .agents/skills/ nach docs/src/ und führt mdbook build docs aus.

• Dokumentation bauen & automatisch veröffentlichen:

  npm run ver
  

  Baut die Dokumentation neu und lädt sie via GitHub Pages auf handbuch.wissen-ahrensburg.de hoch.

🧪 Installation testen

Führe alle Unittests des Workspaces aus, um die korrekte Installation zu bestätigen:

cargo test --workspace

📘 Administrator-Handbuch für MeinCMS (Rust Edition)

Willkommen beim offiziellen Administrator-Handbuch für MeinCMS (wissen-ahrensburg.de).
Dieses Handbuch beschreibt die gesamte Architektur, alle Funktionen, Konfigurationsoptionen, Verwaltungswerkzeuge sowie Best Practices für den sicheren Betrieb im Internet.

📋 Inhaltsverzeichnis

1. Systemübersicht & Architektur
2. Funktionsumfang (Was die Anwendung kann)
3. Installation, Deployment & Betrieb
4. Konfiguration & Umgebungsvariablen
5. Benutzer- & Admin-Verwaltung (meincms_admin)
6. Backup, Import & Repair (meincms_backup)
7. Sicherheit, Datenschutz & Härtung
8. Fehlerbehebung & Wartung

1. Systemübersicht & Architektur

MeinCMS ist als moderner Rust Cargo Workspace aufgebaut. Es besteht aus vier hochperformanten Subsystemen:

flowchart TD
    subgraph Cargo Workspace
        P["meincms_parser\n(Markdown & MediaWiki Compiler Crate)"]
        W["meincms_web\n(Axum 0.7 Async Web Backend)"]
        B["meincms_backup\n(YAML/XML Export, Import & Repair CLI)"]
        A["meincms_admin\n(Argon2 User & Passwords CLI)"]
    end
    W --> P
    B --> P
    A --> P

Die Subsysteme im Detail:

• meincms_parser: Compiler-Crate für Markdown und MediaWiki-Syntax mit automatischer Kategorie-Extraktion, XSS-Escaping und C-FFI-Schnittstellen.
• meincms_web: Async Axum Webserver mit Maud-Templating, Hostname-basiertem Multi-Tenancy (main vs. doc) und rollenbasierter Authentifizierung.
• meincms_backup: CLI-Werkzeug für die datensparende Sicherung und Wiederherstellung von Wiki-Inhalten (YAML & XML).
• meincms_admin: CLI-Werkzeug zur Verwaltung von Administrator-Konten und Argon2id-Passwörtern.

2. Funktionsumfang (Was die Anwendung kann)

✍️ Wiki & Editor

• Duale Syntax-Unterstützung: Artikel können in Markdown oder MediaWiki (WikiText) verfasst werden.
• Dynamische Rhai-Skript-Makros: Admins und Nutzer können eingebettete Rhai-Skripte in Artikeln ausführen, z. B. {{#rhai: 5 * 10}} oder {{#script: "Hallo " + "Welt"}}. Die Skripte sind durch ein Sandbox-Limit (max. Operations-Tiefe) gegen Endlosschleifen geschützt.
• Dynamisches Umschalten: Im Editor lässt sich die Syntax per Dropdown umschalten (style.display).
• Kategorien-System: Automatische Erkennung von [[kategorie:Name]] im Text oder über Frontmatter-Metadaten.
• Versionierung & Historie: Zu jedem Artikel wird bei jeder Änderung eine neue Revisionsversion angelegt. Alte Stände können eingesehen und verglichen werden.

🌐 Multi-Tenancy (Mandantenfähigkeit)

• Automatische Domain-Zuordnung:
  • wissen-ahrensburg.de oder localhost ➔ Mandant main (Haupt-Wiki)
  • doc.wissen-ahrensburg.de oder doc.localhost ➔ Mandant doc (Technische Dokumentation)
• Strikte Daten-Isolation: Inhalte und Suchen werden in der Datenbank isoliert nach TenantId gefiltert.

🔒 Rollenbasierter Schreibschutz (AdminAuth)

• Lesen für alle: Besucher können Artikel, Kategorien und Suchen uneingeschränkt lesen.
• Schreiben nur für Admins: Das Erstellen (/edit/*slug) und Speichern (POST /save/*slug) von Artikeln erfordert zwingend eine aktive Admin-Sitzung. Bei unangemeldetem Zugriff erfolgt eine automatische Umleitung zum Login-Formular (/login).

3. Installation, Deployment & Betrieb

Voraussetzungen

• Rust Compiler (Version 1.80 oder neuer)
• PostgreSQL (Version 14 oder neuer)

1. Bauen im Release-Modus

cd wissen-ahrensburg.de
cargo build --release

Die fertigen Binärdateien befinden sich anschließend in ./target/release/.

2. Manueller Start

PORT=5000 DATABASE_URL="postgres://postgres:passwort@localhost:5432/meincms" ./target/release/meincms_web

3. Einrichtung als Linux Systemd-Dienst (meincms.service)

Erstelle die Datei /etc/systemd/system/meincms.service:

[Unit]
Description=MeinCMS Rust Web Backend
After=network.target postgresql.service

[Service]
Type=simple
User=www-data
WorkingDirectory=/var/www/wissen-ahrensburg.de
ExecStart=/var/www/wissen-ahrensburg.de/target/release/meincms_web
Environment="UNIX_SOCKET=/run/meincms/meincms.sock"
Environment="DATABASE_URL=postgres://meincms:SicheresPasswort@/var/run/postgresql/meincms"
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Dienst aktivieren & starten:

sudo systemctl daemon-reload
sudo systemctl enable meincms
sudo systemctl start meincms

4. Reverse Proxy Setup (Caddy oder Nginx mit Let's Encrypt HTTPS)

Option A: Caddy (Empfohlen - automatische SSL-Zertifikate)

/etc/caddy/Caddyfile:

wissen-ahrensburg.de {
    reverse_proxy localhost:5000
}

doc.wissen-ahrensburg.de {
    reverse_proxy localhost:5000
}

Option B: Nginx

/etc/nginx/sites-available/meincms:

server {
    server_name wissen-ahrensburg.de doc.wissen-ahrensburg.de;

    location / {
        proxy_pass http://127.0.0.1:5000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

5. Dokumentation bauen & veröffentlichen (mdBook)

Die Handbuch-Dokumentation wird automatisiert mit mdBook gebaut und bindet AGENTS.md und alle Subagent-Skills aus .agents/ ein:

• Dokumentation lokal bauen:

  npm run build:docs
  

  (Synchronisiert AGENTS.md & Skills nach docs/src und führt mdbook build docs aus)

• Dokumentation bauen & automatisch veröffentlichen:

  npm run ver
  

  (Baut die Dokumentation inkl. AGENTS.md & Skills und lädt sie via GitHub Pages auf handbuch.wissen-ahrensburg.de hoch)

4. Konfiguration & Umgebungsvariablen

Das Verhalten des Webbackends lässt sich über Umgebungsvariablen steuern:

5. Benutzer- & Admin-Verwaltung (meincms_admin)

Das Werkzeug meincms_admin dient der Verwaltung aller Administratoren.

Interaktiver Modus

cargo run -p meincms_admin

CLI-Befehle

# 1. Benutzer auflisten
cargo run -p meincms_admin -- list-users

# 2. Neuen Administrator erstellen
cargo run -p meincms_admin -- create-user --username admin@wissen-ahrensburg.de

# 3. Passwort eines Benutzers ändern
cargo run -p meincms_admin -- reset-password --username admin@wissen-ahrensburg.de

🔒 Sicherheitshinweis: Passwörter werden mit Argon2id gehasht und in config/users.json bzw. in der Datenbank abgelegt.

6. Backup, Import & Repair (meincms_backup)

Das Werkzeug meincms_backup übernimmt den gesicherten Im- und Export sowie die Reparatur aller Inhalte.

💾 Backup Exportieren

# Exportiert den aktuellen Mandanten als YAML-Datei
cargo run -p meincms_backup -- export mein_backup.yaml

# Exportiert als XML-Datei
cargo run -p meincms_backup -- export mein_backup.xml

# Globaler Export aller Mandanten
cargo run -p meincms_backup -- export full_backup.yaml --full

📥 Backup Importieren

cargo run -p meincms_backup -- import meine_sicherung.yaml

Hinweis: Das Import-Tool erkennt automatisch, ob es sich um ein einzelnes Backup-Objekt oder ein Array von Artikeln handelt und unterstützt Abwärtskompatibilität für alte PascalCase-Formate.

🔧 Repair (HTML Regenerierung)

Um Speicherplatz zu sparen, speichert MeinCMS kein generiertes HTML in Backup-Dateien. Nach einem Import oder nach Änderungen am Parser muss der Repair-Befehl ausgeführt werden:

cargo run -p meincms_backup -- repair

7. Sicherheit, Datenschutz & Härtung

1. Dateisystem-Schutz:
   • Zugriffe auf verdeckte Dateien (/.gitignore, /.env) oder Konfigurationspfade (/config/users.json) werden vom Webserver mit HTTP 403 Forbidden blockiert.
2. Sicherheits-Header:
   • Cache-Control: no-store, no-cache, must-revalidate (Verhindert Zwischenspeicherung sensibler Seiten).
   • X-Frame-Options: DENY (Schutz vor Clickjacking).
   • X-Content-Type-Options: nosniff (Schutz vor MIME-Sniffing).
3. Passwort-Sicherheit:
   • Kein Klartext-Passwort im Quellcode oder in Repositories.
   • Argon2id Hashing mit Salt.

8. Fehlerbehebung & Wartung

Problem: Admin-Passwort vergessen

1. Führe den Admin-CLI Befehl aus:

   cargo run -p meincms_admin -- reset-password --username admin@wissen-ahrensburg.de
   

2. Falls config/users.json beschädigt ist, lösche die Datei: rm -f config/users.json. Beim nächsten Aufruf von meincms_admin wird ein neuer Admin angelegt.

Problem: Port bereits belegt (AddrInUse)

Wenn der Port (z. B. 5000) belegt ist, wähle einen anderen Port:

PORT=5005 cargo run -p meincms_web

Problem: HTML-Seiten zeigen leere Abschnitte

Führe den Repair-Befehl aus, um die HTML-Ausgabe aus dem Quelltext neu zu generieren:

cargo run -p meincms_backup -- repair

Stand: Juli 2026 • Lizenz: AGPL-3.0 • MeinCMS Rust Workspace

📐 System-Architektur, Bausteine & Design Patterns

Dieses Kapitel erklärt den gesamten Aufbau von wissen-ahrensburg.de (MeinCMS) so, dass ihn jeder – vom Entwickler über den Systemadministrator bis hin zu KI-Agenten – schnell und mühelos verstehen kann.

1. Übersicht: Was ist MeinCMS?

MeinCMS ist ein modernes, hochperformantes Wiki- und Content-Management-System (CMS) mit Multi-Tenancy (Mandantenfähigkeit), das vollständig in Rust entwickelt wurde und PostgreSQL als Datenbank nutzt.

flowchart TD
    Client["🌐 Webbrowser / Client"] -->|HTTP Request| WebServer["meincms_web\n(Axum 0.7 Webserver)"]
    WebServer -->|1. Mandanten-Erkennung| Tenant["tenant.rs\n(Hostname Filter)"]
    WebServer -->|2. Datenabfrage| DB["PostgreSQL Datenbank\n(SQLx & Async Pool)"]
    WebServer -->|3. Wiki-Parsing| Parser["meincms_parser\n(Markdown & MediaWiki)"]
    WebServer -->|4. HTML Rendering| Views["views/\n(Maud Typsichere Templates)"]
    Views -->|HTTP HTML Response| Client

    style Client fill:#e1f5fe,stroke:#0288d1
    style WebServer fill:#d7ffd9,stroke:#388e3c
    style Tenant fill:#fff9c4,stroke:#fbc02d
    style DB fill:#f3e5f5,stroke:#ab47bc
    style Parser fill:#ffe0b2,stroke:#f57c00
    style Views fill:#e8f5e9,stroke:#2e7d32

Die wichtigsten Eigenschaften auf einen Blick:

1. 100% Speichersicher & Schnell: Entworfen als Rust-Workspace ohne schwerfällige Runtimes.
2. Multi-Tenancy (Mandantenfähigkeit): Ein einziger Server kann mehrere unabhängige Wikis betreiben (z. B. Haupt-Wiki vs. Technik-Dokumentation), getrennt nach Mandanten-IDs (tenant_id).
3. Zwei Wiki-Syntaxen: Unterstützt klassisches Markdown und MediaWiki-Wikitext.
4. Keine Inline-Skripte / XSS-Schutz: Höchste Sicherheit durch automatisches HTML-Escaping in Maud und No-Cache-Middleware.

2. Die 4 Kernbausteine (Rust Crates)

Das Projekt ist in 4 spezialisierte Pakete (Crates) unterteilt, die zusammen den Rust Workspace bilden:

graph TD
    subgraph Rust Workspace (Cargo.toml)
        WEB["meincms_web\n(Axum Webanwendung & Maud UI)"]
        PARSER["meincms_parser\n(Markdown, MediaWiki & C-FFI Export)"]
        BACKUP["meincms_backup\n(CLI: Export, Import & Repair)"]
        ADMIN["meincms_admin\n(CLI: User- & Passwort-Verwaltung)"]
    end

    WEB -->|Nutzt als Dependency| PARSER
    BACKUP -->|Nutzt als Dependency| PARSER

3. Datenfluss: Wie verarbeitet das System eine Anfrage?

Wenn ein Benutzer eine Wiki-Seite aufruft (z. B. https://wissen-ahrensburg.de/wiki/Hauptseite), passiert Folgendes:

1. Routing & Middleware (meincms_web): Der Axum Webserver nimmt den HTTP-Request entgegen. Die Tenant-Middleware liest den Hostnamen aus und bestimmt den aktuellen Mandanten (main oder doc).
2. Datenbankabfrage (db.rs): Über SQLx wird der gewünschte Artikel für diesen Mandanten aus der PostgreSQL-Datenbank geladen.
3. Text-Transformation (meincms_parser): Der gespeicherte Rohtext (Markdown oder MediaWiki) wird an meincms_parser übergeben und blitzsicher in HTML konvertiert.
4. HTML-Generierung (views/): Maud (ein typsicheres Rust-Makro) baut das vollständige HTML-Dokument zusammen (Navigation, Artikelinhalt, Footer).
5. Antwort senden: Der Server sendet das fertige HTML mit No-Cache-Sicherheitsheadern an den Browser zurück.

4. Software-Entwurfsmuster (Design Patterns) im Projekt

Um den Code sauber, wartbar und erweiterbar zu halten, werden bewährte Entwurfsmuster eingesetzt:

graph LR
    subgraph Design Patterns
        P1["1. Repository Pattern\n(db.rs)"]
        P2["2. Strategy Pattern\n(Parser Pipeline)"]
        P3["3. Middleware Chain\n(Axum / Tower)"]
        P4["4. Component Pattern\n(Maud Views)"]
        P5["5. FFI Adapter Pattern\n(C-ABI Export)"]
    end

🗄️ 1. Repository Pattern (Datenzugriffsschicht in db.rs)

• Konzept: Die Webanwendung greift nicht direkt mit rohen SQL-Strings in Handlern auf die Datenbank zu, sondern nutzt Datenzugriffsfunktionen in db.rs.
• Vorteil: SQL-Abfragen sind zentral gebündelt. Bei Datenbankänderungen muss nur db.rs angepasst werden.

🔄 2. Strategy Pattern (Parser-Auswahl in meincms_parser)

• Konzept: Artikel können in Markdown oder MediaWiki-Syntax vorliegen. Das System wählt je nach Artikeltyp dynamisch die passende Parser-Strategie (markdown::render oder wikitext::render).
• Vorteil: Neue Formate (z. B. Org-Mode oder AsciiDoc) können als neue Strategie hinzugefügt werden, ohne die Webanwendung zu verändern.

⛓️ 3. Middleware Chain Pattern (Axum / Tower Services in tenant.rs & auth.rs)

• Konzept: Jede Anfrage durchläuft eine Kette von Filtern:
  1. Multi-Tenancy Filter: Welcher Mandant ruft auf?
  2. Authentication Filter: Ist der Admin eingeloggt?
  3. Security Header Filter: Werden No-Cache und X-Content-Type-Options erzwungen?
• Vorteil: Klare Trennung von Sicherheits- und Geschäftslogik (Separation of Concerns).

🧩 4. Component-Based UI Pattern (Maud Templates in views/)

• Konzept: Statt schwerfälliger Template-Dateien (wie Jinja2 oder HTML-Dateien) wird die Benutzeroberfläche in kleinen, wiederverwendbaren Rust-Funktionen aufgebaut.
• Vorteil: Kompilierzeit-Prüfung aller HTML-Strukturen, kein Tippfehler bei Variablen und automatisches XSS-Escaping.

🔌 5. FFI Adapter Pattern (C-ABI Hülle in ffi.rs)

• Konzept: Der Rust-Parser stellt über C-kompatible Funktionsaufrufe (extern "C") und eine Header-Datei (meincms_parser.h) eine Schnittstelle für externe Sprachen (C, C++, Node.js, Python) bereit.
• Vorteil: Das Parser-Crate kann außerhalb des Rust-Ökosystems als native Shared Library (.so / .dll) wiederverwendet werden.

5. Datenbank-Schema & Datenmodell (PostgreSQL)

Die Datenbank verwendet ein klares, relationales Schema mit strikter Mandantentrennung:

erDiagram
    WIKI_ARTIKEL ||--o{ WIKI_ARTIKEL_VERSION : "hat Historie"
    WIKI_NAMESPACE ||--o{ WIKI_ARTIKEL : "gruppiert"
    WIKI_CATEGORY ||--o{ WIKI_ARTIKEL : "kategorisiert"

    WIKI_ARTIKEL {
        uuid id PK
        string tenant_id FK "Mandanten-ID (main / doc)"
        string slug "Eindeutiger URL-Pfad"
        string title "Titel des Artikels"
        string content_markdown "Markdown Inhalt"
        string content_mediawiki "MediaWiki Inhalt"
        uuid namespace_id FK
    }

    WIKI_ARTIKEL_VERSION {
        uuid id PK
        uuid artikel_id FK
        integer version_number
        string content
        timestamp created_at
    }

• Mandantentrennung: Alle Tabellen filtern standardmäßig über tenant_id. Datensätze verschiedener Mandanten können sich niemals vermischen.
• Historisierung: Bei jeder Artikeländerung wird eine neue WIKI_ARTIKEL_VERSION angelegt, wodurch Änderungen rückgängig gemacht werden können.

💡 Zusammenfassung für Entwickler & KI-Agenten

1. Wo erstelle ich neue Funktionen?
   • Neue HTTP-Endpunkte -> meincms_web/src/handlers.rs
   • Neue UI-Komponenten -> meincms_web/src/views/
   • Datenbank-Abfragen -> meincms_web/src/db.rs
   • Parser-Erweiterungen -> meincms_parser/src/
2. Wie teste und baue ich das Projekt?
   • Prüfen: cargo check & cargo test --workspace
   • Linter: cargo clippy
   • Doku bauen: npm run build:docs

📚 Externe Bibliotheken & Crates

Diese Dokumentation bietet einen vollständigen und detaillierten Überblick über alle externen Rust-Crates und Bibliotheken, die im Projekt MeinCMS (wissen-ahrensburg.de) verwendet werden.

MeinCMS ist als modularer Rust Workspace aufgebaut. Jedes Subsystem (meincms_parser, meincms_web, meincms_backup, meincms_admin) nutzt spezialisierte, hochperformante Open-Source-Bibliotheken für seine jeweiligen Aufgaben.

📋 Schnellübersicht aller Abhängigkeiten

🧩 Details nach Subsystemen

1. meincms_parser (Markdown & MediaWiki Compiler)

Das Crate meincms_parser ist das Herzstück der Inhaltsverarbeitung. Es wandelt Benutzereingaben (Markdown oder MediaWiki/WikiText) sicher in HTML um und führt dynamische Skripte aus.

• regex (v1.10):
  • Zweck: Auswertung und Erkennung von Wiki-Syntaxstrukturen wie Wikilinks ([[Titel]]), Kategorie-Tags ([[kategorie:Name]]), Frontmatter und Makro-Blöcken ({{#rhai: ...}}).
  • Warum gewählt: Standard-Regex-Engine für Rust, hochoptimiert und gegen ReDoS-Angriffe (Regular Expression Denial of Service) geschützt.
• html-escape (v0.2):
  • Zweck: Entschärfen potenziell gefährlicher Zeichen (<, >, &, ", ') vor der HTML-Generierung.
  • Warum gewählt: Gewährleistet strikten Schutz gegen Cross-Site-Scripting (XSS), da unsicherer Benutzercode niemals unmaskiert gerendert wird.
• rhai (v1.19):
  • Zweck: Eingebettete Skriptsprache zur Ausführung dynamischer Makros in Wiki-Artikeln (z. B. mathematische Berechnungen, Zeichenkettenoperationen).
  • Warum gewählt: Rhai wurde speziell für Rust entwickelt, kompiliert ohne externe C-Abhängigkeiten und bietet ein konfigurierbares Ausführungslimit (Sandbox), das Endlosschleifen verhindert.
• serde (v1.0) & serde_json (v1.0):
  • Zweck: Umwandlung interner AST-Metadaten (Abstract Syntax Tree) und C-FFI Export-Datenstrukturen in/aus JSON.

2. meincms_web (Axum Async Web-Backend)

Das Subsystem meincms_web stellt das eigentliche Webseiten-Backend für Besucher und Administratoren bereit.

• axum (v0.7):
  • Zweck: Asynchrones Web-Framework für Routing, Request-Handler, Extractor-Mechanismen und Server-Antworten.
  • Warum gewählt: Entwickelt vom Tokio-Team, bietet maximale Ergonomie, Typen-Sicherheit und exzellente Performance ohne Laufzeit-Overhead.
• tokio (v1.x, Feature full):
  • Zweck: Event-gesteuerte asynchrone Runtime für Multithreading, I/O-Operationen und Server-Sockets.
  • Warum gewählt: Der De-facto-Standard in der Rust-Ökosystem für performante Netzwerkanwendungen.
• sqlx (v0.8, Features: postgres, runtime-tokio-rustls, chrono, json):
  • Zweck: Asynchroner PostgreSQL-Datenbanktreiber und Query-Builder.
  • Warum gewählt: Bietet Typsicherheit beim Ausführen von Datenbankabfragen und unterstützt native Unix Domain Sockets (/var/run/postgresql/meincms) sowie JSON-Spalten.
• maud (v0.26):
  • Zweck: Schreiben von HTML-Templates direkt in Rust-Code via html! { ... } Makro.
  • Warum gewählt: Maud-Templates werden zur Compile-Zeit in hochoptimierten Rust-Code umgewandelt. Das vermeidet Parsing-Kosten zur Laufzeit und macht XSS-Escaping typsicher.
• tower-http (v0.6) & tower (v0.5):
  • Zweck: Middleware-Komponenten für Komprimierung (Brotli & Gzip), Ausliefern statischer CSS/JS-Dateien, CORS und Request-Logging.
• hyper (v1.x) & hyper-util (v0.1):
  • Zweck: Unterbau für den HTTP-Server. Ermöglicht das Binden des Webservers an TCP-Ports oder Unix-Domain-Sockets (UNIX_SOCKET).
• tracing (v0.1) & tracing-subscriber (v0.3):
  • Zweck: Strukturierte Diagnose- und Log-Ausgaben im Serverbetrieb. Steuerung der Detailtiefe über die Umgebungsvariable RUST_LOG.
• dotenvy (v0.15):
  • Zweck: Automatisches Laden von Konfigurationswerten aus einer .env-Datei beim Anwendungsstart.
• chrono (v0.4):
  • Zweck: Datums- und Zeitberechnungen für Artikel-Revisionen und HTTP-Header.

3. meincms_backup (YAML/XML Export, Import & Repair CLI)

Das CLI-Werkzeug meincms_backup dient der Datensicherung, Datenmigration und der Regenerierung beschädigter HTML-Inhalte.

• clap (v4.5, Feature derive):
  • Zweck: Verarbeiten von Befehlszeilen-Argumenten und Optionen (export, import, repair, --full).
  • Warum gewählt: Deklarative Definition von CLI-Interfaces mit automatischer Generierung von Hilfetexten (--help).
• serde_yaml (v0.9):
  • Zweck: Serialisierung und Deserialisierung von Wiki-Artikeln in gut lesbare YAML-Sicherungsdateien.
• quick-xml (v0.37):
  • Zweck: Extrem schnelles Lesen und Schreiben von XML-Sicherungen.
  • Warum gewählt: Verarbeitet selbst sehr große XML-Backups mit minimalem Speicherbedarf.
• sqlx & tokio:
  • Zweck: Direktes Einlesen und Zurückschreiben von Datensätzen in die PostgreSQL-Datenbank im CLI-Kontext.

4. meincms_admin (User- & Admin-Management CLI)

Das Werkzeug meincms_admin dient der sicheren Verwaltung von Administrator-Konten und Zugangsdaten.

• argon2 (v0.5):
  • Zweck: Hashen und Überprüfen von Administrator-Passwörtern nach dem Argon2id-Standard.
  • Warum gewählt: Sieger der Password Hashing Competition (PHC). Bietet höchstmöglichen Schutz gegen GPU- und ASIC-basierte Brute-Force-Angriffe durch konfigurierbare Speicher- und Zeitkomplexität.
• rpassword (v7.3):
  • Zweck: Sicheres Einlesen von Passwörtern im Terminal ohne Konsolenausgabe (Kein Echo des Passworts auf dem Bildschirm).
• clap (v4.5) & serde_json (v1.0):
  • Zweck: CLI-Steuerung und Speichern der Admin-Konfiguration (config/users.json).

🔒 Sicherheits- & Wartungshinweise

1. Abhängigkeits-Analyse mit deps & cargo tree: Ein Tool zur Analyse der Abhängigkeiten eines Projekts. Es hilft dabei, transitive Abhängigkeiten zu verstehen und doppelte Crates aufzuspüren:

   cargo tree
   

   Ebenfalls steht über https://deps.dev (Google Open Source Insights) eine tiefgehende Analyse der Abhängigkeiten bereit.

2. Sicherheits-Audits mit osv (Open Source Vulnerabilities): osv ist eine verteilte Schwachstellendatenbank für Open Source (osv.dev). Das CLI-Tool osv-scanner ermöglicht sprachübergreifende Audits:

   go install github.com/google/osv-scanner/v2/cmd/osv-scanner@v2
   osv-scanner -r path/to/your/project
   

3. Alternative Scanner zu OSV-Scanner (Trivy, Grype, Semgrep):

   • Trivy (Aqua Security): Open-Source Scanner für Dateisysteme & Abhängigkeiten (trivy fs /pfad/zum/projekt).
   • Grype (Anchore): Schneller Schwachstellenscanner für Verzeichnisse & SBOMs (grype dir:/pfad/zum/projekt).
   • Semgrep: Regelbasierte statische Code-Analyse / SAST (semgrep scan).

4. Statische Code-Analyse & Vulnerability Scanning mit Snyk: Snyk ermöglicht statische Quellcode-Analysen (SAST) sowie Scans von Projektschnittstellen:

   npm install -g snyk
   snyk auth
   snyk code test
   # Oder spezifischer Pfad:
   snyk code test /pfad/zum/code
   

5. RustSec Security Audits (cargo audit): Um Sicherheitslücken in externen Crates frühzeitig zu erkennen, sollte regelmäßig cargo audit ausgeführt werden:

   cargo install cargo-audit
   cargo audit
   

6. Aktualisierung der Crates: Crates innerhalb der angegebenen Minor-Versionen können mit folgendem Befehl auf den neuesten Stand gebracht werden:

   cargo update
   

7. Lizenzkonformität: Alle verwendeten Bibliotheken nutzen verträgliche Open-Source-Lizenzen (wie MIT, Apache-2.0 oder BSD), die vollständig mit der AGPL-3.0-Lizenz von MeinCMS kompatibel sind.

⚙️ C-API / C-ABI, Conan, NPM & PIP Paketmanager

Dieses Kapitel beschreibt die plattformübergreifenden Schnittstellen und Paketmanager-Integrationen von MeinCMS (wissen-ahrensburg.de). Es erläutert die C-API / C-ABI Exporte des Parser-Crates, die Paketierung für C/C++ über Conan sowie Ubuntu Linux-Alternativen (APT, vcpkg, pkg-config, CMake, Ubuntu Security Portale), die verwendeten NPM-Pakete für Dokumentations-Builds sowie die Anbindung an das Python/PIP-Ökosystem.

1. C-API & C-ABI Interface (meincms_parser)

Das Subsystem meincms_parser bietet eine native C-ABI (Application Binary Interface)-Schnittstelle, die es erlaubt, den Hochleistungs-Parser in externen C-, C++- oder Fremdsprachen-Projekten (Python, PHP, Go, C#) einzubinden.

Configuration in Cargo.toml

Durch die Angabe von cdylib baut Cargo bei cargo build eine dynamische C-Bibliothek (libmeincms_parser.so unter Linux, .dylib unter macOS, .dll unter Windows):

[lib]
crate-type = ["cdylib", "rlib"]

Exportierte C-Funktionen (src/ffi.rs)

Alle exportierten Funktionen nutzen #[no_mangle] und unsafe extern "C" zur Einhaltung der Standard C-Aufrufkonvention.

⚠️ Wichtiger Speicherhinweis: Rückgabewerte vom Typ *mut c_char werden von Rust allokiert und müssen in C/C++ nach Nutzung zwingend mit meincms_free_string(ptr) freigegeben werden, um Speicherlecks zu vermeiden!

Header-Datei (meincms_parser.h) für C / C++

#ifndef MEINCMS_PARSER_H
#define MEINCMS_PARSER_H

#ifdef __cplusplus
extern "C" {
#endif

// Wandelt Markdown in HTML um
char* meincms_markdown_to_html(const char* input);

// Extrahiert Kategorien aus Markdown als JSON-String
char* meincms_markdown_get_categories(const char* input);

// Wandelt WikiText in HTML um
char* meincms_wikitext_to_html(const char* input);

// Extrahiert Kategorien aus WikiText als JSON-String
char* meincms_wikitext_get_categories(const char* input);

// Gibt CString Speicher auf dem Rust-Heap frei
void meincms_free_string(char* ptr);

#ifdef __cplusplus
}
#endif

#endif // MEINCMS_PARSER_H

C++ Verwendungsbeispiel

#include <iostream>
#include "meincms_parser.h"

int main() {
    const char* markdown = "# Hallo Welt\nDies ist ein **Test** mit [[kategorie:Dokumentation]].";
    
    // HTML konvertieren
    char* html = meincms_markdown_to_html(markdown);
    std::cout << "HTML Output: " << html << std::endl;
    meincms_free_string(html); // Speichergabe

    // Kategorien extrahieren
    char* categories_json = meincms_markdown_get_categories(markdown);
    std::cout << "Kategorien (JSON): " << categories_json << std::endl;
    meincms_free_string(categories_json); // Speichergabe

    return 0;
}

2. Conan Paketmanager & Ubuntu Linux Alternativen

2.1 Conan Paketmanager

Conan ist ein verbreiteter, plattformübergreifender C/C++ Paketmanager. Um meincms_parser als wiederverwendbares Paket in C/C++-Projekte (z. B. via CMake) einzubinden, kann ein conanfile.py verwendet werden.

Beispiel conanfile.py für meincms_parser

from conan import ConanFile
from conan.tools.files import copy
import os

class MeinCmsParserConan(ConanFile):
    name = "meincms_parser"
    version = "0.1.0"
    license = "AGPL-3.0"
    author = "Thorsten Klöhn"
    url = "https://github.com/thorstenkloehn/wissen-ahrensburg.de"
    description = "Rust-based Markdown & MediaWiki Parser C-FFI Library"
    topics = ("markdown", "wikitext", "parser", "rust", "c-ffi")
    settings = "os", "compiler", "build_type", "arch"

    def build(self):
        # Baut die Rust-Bibliothek via Cargo
        self.run("cargo build --release -p meincms_parser")

    def package(self):
        # Kopiert C-Header und Binärdateien (.so / .dylib / .dll / .a)
        copy(self, "meincms_parser.h", src=self.source_folder, dst=os.path.join(self.package_folder, "include"))
        copy(self, "*.so", src=os.path.join(self.source_folder, "target", "release"), dst=os.path.join(self.package_folder, "lib"))
        copy(self, "*.dylib", src=os.path.join(self.source_folder, "target", "release"), dst=os.path.join(self.package_folder, "lib"))
        copy(self, "*.dll", src=os.path.join(self.source_folder, "target", "release"), dst=os.path.join(self.package_folder, "lib"))

    def package_info(self):
        self.cpp_info.libs = ["meincms_parser"]

Einbindung in C++ CMake-Projekten

cmake_minimum_required(VERSION 3.15)
project(MeinApp CXX)

find_package(meincms_parser REQUIRED)

add_executable(mein_app main.cpp)
target_link_libraries(mein_app PRIVATE meincms_parser::meincms_parser)

2.2 Alternativen zu Conan auf Linux Ubuntu

Falls Conan auf Ubuntu Linux nicht verwendet werden soll, stehen folgende professionelle Alternativen zur Verfügung:

1. Nativer Ubuntu System-Paketmanager (APT / .deb Paket via cargo-deb)

Unter Ubuntu kann aus dem Rust-Projekt direkt ein nativ installierbares Debian/Ubuntu-Paket (.deb) gebaut werden:

# Cargo DEB Tool installieren
cargo install cargo-deb

# .deb Paket für meincms_parser bauen
cargo deb -p meincms_parser

# Unter Ubuntu installieren
sudo dpkg -i target/debian/meincms_parser_0.1.0_amd64.deb

Dabei wird libmeincms_parser.so nach /usr/lib/ und meincms_parser.h nach /usr/include/ installiert. Jeder C/C++ Compiler unter Ubuntu (GCC/Clang) findet die Bibliothek nun systemweit ohne Konfiguration.

2. pkg-config Integration (meincms_parser.pc)

pkg-config ist der Standard auf Ubuntu Linux, um C/C++-Bibliothekspfade automatisch aufzulösen.

Erstelle die Datei /usr/lib/pkgconfig/meincms_parser.pc:

prefix=/usr
exec_prefix=${prefix}
libdir=${exec_prefix}/lib
includedir=${prefix}/include

Name: meincms_parser
Description: High-Performance Rust Markdown & MediaWiki Parser C-FFI
Version: 0.1.0
Libs: -L${libdir} -lmeincms_parser
Cflags: -I${includedir}

Kompilieren unter Ubuntu mit GCC / Clang:

gcc main.c $(pkg-config --cflags --libs meincms_parser) -o mein_programm

3. vcpkg (Microsoft C/C++ Package Manager for Linux/Ubuntu)

vcpkg ist eine weit verbreitete Conan-Alternative für Ubuntu Linux. Es lässt sich nahtlos in CMake integrieren:

# vcpkg unter Ubuntu installieren
git clone https://github.com/microsoft/vcpkg.git
./vcpkg/bootstrap-vcpkg.sh

# Einbinden in CMake
cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=/pfad/zu/vcpkg/scripts/buildsystems/vcpkg.cmake

4. CMake ExternalProject / FetchContent (Ohne externen Paketmanager)

CMake kann unter Ubuntu direkt beim Konfigurieren den Rust Cargo Build anstoßen:

include(ExternalProject)
ExternalProject_Add(
    meincms_parser_target
    SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/path/to/meincms_parser
    BUILD_COMMAND cargo build --release
    INSTALL_COMMAND ""
)

2.3 Ubuntu Security Portal & Prüfung einzelner C/C++ Pakete

Für die Verifizierung und Prüfung der Sicherheit einzelner C-Bibliotheken und Pakete unter Ubuntu stehen folgende offizielle Ressourcen und Werkzeuge bereit:

1. Offizielle Ubuntu Security Webseiten & CVE-Datenbanken

• Ubuntu Security Notices (USN):
  🔗 https://ubuntu.com/security/notices
  Hier veröffentlicht Canonical alle offiziellen Sicherheits-Patches, Updates und Warnungen für einzelne C-Pakete und Systembibliotheken.

• Ubuntu CVE Tracker & Paketsuche:
  🔗 https://ubuntu.com/security/cve
  Ermöglicht die gezielte Suche nach Sicherheitslücken (CVEs) für einzelne C-Pakete (z. B. glibc, openssl, zlib, curl, libssl).

• Ubuntu Package Directory:
  🔗 https://packages.ubuntu.com
  Informationen zu allen Quell- und Binärpaketen und deren Zugehörigkeit zu Repositories (main, universe, security).

2. Befehle zur Sicherheitsprüfung auf lokalen Ubuntu-Systemen

# 1. Sicherheitsstatus von Ubuntu Pro & ESM (Security Patches) prüfen
pro status

# 2. Prüfen, aus welchem Security-Repository ein C-Paket bezogen wurde (z.B. noble-security)
apt-cache policy libssl3 libc6

# 3. Bekannte CVEs auf dem eigenen Ubuntu-System auswerten (benötigt debsecan)
sudo apt install debsecan
debsecan

3. Compiler-Härtung für C/C++ Pakete unter Ubuntu

Beim Kompilieren von C/C++ Anwendungen, die libmeincms_parser.so einbinden, sollten unter Ubuntu stets die offiziellen Canonical Hardening Flags verwendet werden:

gcc -O2 -fstack-protector-strong -D_FORTIFY_SOURCE=2 -fPIE -pie -Wl,-z,relro,-z,now main.c -lmeincms_parser -o main_app

3. NPM Paketmanager & Scripts

Für die Verwaltung, Generierung und Veröffentlichung der Handbuch-Dokumentation wird Node.js und npm eingesetzt.

package.json Übersicht

{
  "name": "wissen-ahrensburg.de",
  "version": "1.0.0",
  "description": "Ein hochperformantes, mandantenfähiges (Multi-Tenancy) Wiki-CMS System, vollständig in Rust entwickelt.",
  "directories": {
    "doc": "docs"
  },
  "scripts": {
    "build:docs": "node scripts/build_docs.js",
    "ver": "npm run build:docs && npx -y gh-pages -d docs/book --nojekyll --cname handbuch.wissen-ahrensburg.de"
  },
  "dependencies": {
    "github-pages": "^0.1.0"
  }
}

Verwendete NPM Pakete

1. gh-pages:

   • Ein Utility-Paket zur automatischen Veröffentlichung des vom mdBook erzeugten HTML-Ordners (docs/book) auf den gh-pages-Branch in GitHub.
   • Flag --nojekyll: Deaktiviert Jekyll-Processing auf GitHub Pages für korrekte Auslieferung aller Unterordner.
   • Flag --cname handbuch.wissen-ahrensburg.de: Setzt automatisch die Custom-Domain der Dokumentation.

2. github-pages:

   • Unterstützendes Abhängigkeitspaket für GitHub-Pages Hilfsklassen und Konfiguration.

4. Python & PIP Ökosystem (Python FFI Bindings & PIP Paketierung)

Neben C und C++ kann der meincms_parser auch direkt in Python mittels des Standard-Moduls ctypes oder über ein mit pip installierbares Python-Paket eingebunden werden.

Einbindung in Python mit ctypes

Da meincms_parser eine C-ABI dynamische Bibliothek erzeugt (libmeincms_parser.so), kann Python sie ohne zusätzliche C-Extensions laden:

import ctypes
import json
import os

# Pfad zur kompilierten Shared Library (.so / .dylib / .dll)
lib_path = os.path.abspath("target/release/libmeincms_parser.so")
lib = ctypes.CDLL(lib_path)

# Signaturen definieren
lib.meincms_markdown_to_html.argtypes = [ctypes.c_char_p]
lib.meincms_markdown_to_html.restype = ctypes.c_char_p

lib.meincms_markdown_get_categories.argtypes = [ctypes.c_char_p]
lib.meincms_markdown_get_categories.restype = ctypes.c_char_p

lib.meincms_free_string.argtypes = [ctypes.c_char_p]
lib.meincms_free_string.restype = None

def render_markdown(text: str) -> str:
    encoded = text.encode("utf-8")
    raw_ptr = lib.meincms_markdown_to_html(encoded)
    result = ctypes.cast(raw_ptr, ctypes.c_char_p).value.decode("utf-8")
    lib.meincms_free_string(raw_ptr) # Speichergabe
    return result

def get_categories(text: str) -> list:
    encoded = text.encode("utf-8")
    raw_ptr = lib.meincms_markdown_get_categories(encoded)
    result_json = ctypes.cast(raw_ptr, ctypes.c_char_p).value.decode("utf-8")
    lib.meincms_free_string(raw_ptr) # Speichergabe
    return json.loads(result_json)

if __name__ == "__main__":
    sample = "# Hallo aus Python\nInhalt mit [[kategorie:PythonTest]]."
    print("HTML:", render_markdown(sample))
    print("Kategorien:", get_categories(sample))

Python-Paketierung (pyproject.toml / pip install)

Um den Parser als pip-Paket zu verteilen, kann ein pyproject.toml in Kombination mit setuptools oder maturin (für native Rust-Python Bindings) genutzt werden:

[build-system]
requires = ["setuptools>=61.0", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "meincms_parser"
version = "0.1.0"
description = "Python Bindings for MeinCMS Rust Markdown & MediaWiki Parser"
authors = [{ name = "Thorsten Klöhn" }]
license = { text = "AGPL-3.0" }
dependencies = []

PIP Installation & Verwendung

• Installation im Entwicklungsmodus: pip install -e .
• Erstellen von Distribution-Wheels: pip wheel .

🛡️ Sicherheits-Handbuch: Ubuntu, Rust & NPM Ökosystem

Dieses Dokument bietet eine vollständige Übersicht aller offiziellen Sicherheitsportale, CVE-Datenbanken und CLI-Werkzeuge zur Überprüfung von Sicherheitslücken in C/Ubuntu-Paketen, Rust Crates sowie NPM Node.js Paketen.

1. Ubuntu Linux & C/C++ Sicherheitsportale

Canonical betreibt dedizierte Sicherheitsservices für alle C-Pakete und Systembibliotheken (glibc, openssl, zlib, curl):

Offizielle Ubuntu Webseiten

• Ubuntu Security Notices (USN):
  🔗 https://ubuntu.com/security/notices
  Offizielle Ankündigungen aller Sicherheitsupdates und Patches für Ubuntu-Pakete.

• Ubuntu CVE Tracker:
  🔗 https://ubuntu.com/security/cve
  Gezielte Suche nach spezifischen Sicherheitslücken (CVEs) in einzelnen Paketen.

• Ubuntu Package Directory:
  🔗 https://packages.ubuntu.com
  Übersicht aller Quell- und Binärpakete (main, universe, security).

Ubuntu Terminal-Befehle

• pro status: Prüft den allgemeinen Sicherheits- und ESM-Status (Expanded Security Maintenance).
• apt-cache policy <paketname>: Zeigt Paketversion und Security-Repository-Herkunft (z.B. noble-security).
• debsecan: Analysiert installierte Pakete auf bekannte CVEs (sudo apt install debsecan && debsecan).

C / C++ Statische & Dynamische Sicherheits-Scanner (SAST & Memory Safety)

Für C-Pakete und C/C++-Schnittstellen (wie den C-ABI Export meincms_parser.h) kommen spezialisierte SAST- und Laufzeit-Scanner zum Einsatz:

• Flawfinder (SAST für C/C++):
  Scannt C/C++-Quellcode auf bekannte Sicherheitsrisiken und unsichere API-Funktionen (z.B. strcpy, sprintf):

  sudo apt install flawfinder
  flawfinder .
  

• Cppcheck (Statische C/C++ Analyse):
  Spürt Buffer Overflows, Speicherlecks, Nullpointer-Dereferenzierungen und uninitialisierte Variablen auf:

  sudo apt install cppcheck
  cppcheck --enable=all --suppress=missingIncludeSystem .
  

• Clang-Tidy & Clang Static Analyzer:
  LLVM-basierte statische Code-Analyse zur Überprüfung von C/C++ Sicherheitsregeln (CERT / MISRA):

  clang-tidy --checks='clang-analyzer-*,cert-*' main.c
  

• AddressSanitizer (ASan) & Valgrind (Dynamische Speicherprüfung):
  Erkennt Speicherzugriffsfehler (Use-After-Free, Out-of-Bounds, Memory Leaks) zur Laufzeit:

  # Valgrind Laufzeitanalyse
  sudo apt install valgrind
  valgrind --leak-check=full ./mein_c_programm
  
  # AddressSanitizer beim GCC/Clang Kompilieren aktivieren
  gcc -fsanitize=address -g main.c -lmeincms_parser -o main_app
  

2. Rust Ökosystem Sicherheitsportale & Audit Tools

Das Rust-Ökosystem verfügt über eine hochmoderne, automatisierte Sicherheitsinfrastruktur zur Überprüfung aller Cargo-Abhängigkeiten (crates.io).

Offizielle Rust Security Webseiten

• RustSec Security Advisory Database:
  🔗 https://advisories.rust-lang.org
  Die offizielle Datenbank aller gemeldeten Sicherheitslücken (Advisories) und zerschlagenen („yanked“) Crates auf crates.io.

• GitHub RustSec Advisory Repository:
  🔗 https://github.com/rustsec/advisories
  Das Quellcode-Repository der Rust-Sicherheitsdatenbank (Community-gepflegt).

• Rust Language Security Notices:
  🔗 https://blog.rust-lang.org/category/security.html
  Offizieller Rust-Blog für kritische Sicherheitsmeldungen zu Compiler, Standardbibliothek (std) und Cargo.

Rust Terminal-Befehle & CLI Tools

• cargo audit (Empfohlen):
  Scannt die Datei Cargo.lock des Projekts automatisch gegen die RustSec-Datenbank und meldet bekannte Sicherheitslücken:

  # Installation (einmalig)
  cargo install cargo-audit
  
  # Sicherheitsprüfung im Workspace ausführen
  cargo audit
  

• cargo deny:
  Prüft den Workspace nicht nur auf Sicherheitslücken, sondern auch auf unerwünschte Lizenzen und doppelte Abhängigkeiten:

  cargo install cargo-deny
  cargo deny check
  

• cargo-geiger (Rust Speicher-Sicherheitswert & unsafe Rating):
  Analysiert das Projekt und alle Abhängigkeiten auf die Verwendung von unsafe Rust-Code und berechnet den relativen Sicherheitswert:

  cargo install cargo-geiger
  cargo geiger
  

• Miri (Undefined Behavior Detection in Rust):
  Offizieller Rust Mid-level IR (MIR) Interpreter zur Feststellung von undefiniertem Verhalten (Undefined Behavior, Memory Leaks, Data Races) in unsafe-Rust-Code:

  rustup component add miri
  cargo miri test
  

• deps (cargo-deps, cargo tree & deps.dev):
  Ein Tool zur Analyse der Abhängigkeiten eines Projekts. Es verarbeitet Abhängigkeitsbäume, identifiziert veraltete oder doppelte Crates und visualisiert Abhängigkeitsgraphen:

  # Visualisierung des Abhängigkeitsbaums im Terminal
  cargo tree
  
  # Erstellung eines visuellen Abhängigkeitsgraphen via cargo-deps
  cargo install cargo-deps
  cargo deps | dot -Tpng > deps_graph.png
  
  # Online-Analyse über Google Open Source Insights: https://deps.dev
  

3. NPM & Node.js Ökosystem Sicherheitsportale & Audit Tools

Auch für NPM-Pakete existieren globale Datenbanken und integrierte Auditing-Werkzeuge.

Offizielle NPM Security Webseiten

• GitHub Advisory Database (NPM Security):
  🔗 https://github.com/advisories?query=type%3Anpm
  Die zentrale GitHub/NPM Datenbank zur Abfrage aller CVEs und advisories für Node.js/NPM Pakete.

• NPM Security Documentation & Best Practices:
  🔗 https://docs.npmjs.com/auditing-package-dependencies-for-security-vulnerabilities
  Dokumentation zum automatischen Sicherheits-Audit von Paketabhängigkeiten.

NPM Terminal-Befehle & CLI Tools

• npm audit:
  Vergleicht package.json und package-lock.json automatisch mit der GitHub Advisory Database:

  npm audit
  

• npm audit fix:
  Aktualisiert verwundbare Pakete automatisch auf die nächstsichere Version (ohne Breaking Changes).

• ESLint Security Plugin (eslint-plugin-security - SAST für JS/TS):
  Statische Code-Analyse speziell für JavaScript & Node.js zur Erkennung unsicherer Befehle (eval(), ReDoS-Regex, Unsanitized Inputs, Child Processes):

  # Installation des Security Plugins
  npm install --save-dev eslint eslint-plugin-security
  
  # Ausführung des Security-Linter-Scans
  npx eslint --plugin security --rule 'security/detect-object-injection: error' .
  

• Retire.js (Vulnerability Scanner für JS-Bibliotheken):
  Spezialisierter Scanner zur Erkennung bekannter Sicherheitslücken in JavaScript-Dateien und NPM-Paketen:

  # Globale Installation
  npm install -g retire
  
  # Scan des Projekt-Ordners
  retire --path .
  

• npm ls & npm outdated (Abhängigkeits-Analyse):
  Analysiert die Baumstruktur aller NPM-Pakete und hebt veraltete Bibliotheken hervor:

  # Abhängigkeitsbaum anzeigen
  npm ls --all
  
  # Veraltete Pakete prüfen
  npm outdated
  

NPM Security & Package Rating (Paket-Sicherheitsbewertung)

• Socket.dev (Supply-Chain-Security Rating):
  🔗 https://socket.dev
  Analysiert NPM-Pakete auf Verhaltensrisiken wie versteckte Telemetrie, Install-Skripte, Typosquatting und Berechtigungen (Netzwerk, Dateisystem).

• npms.io (NPM Package Quality & Health Score):
  🔗 https://npms.io
  Berechnet einen kombinierten Score (Quality, Maintenance, Popularity) für jedes NPM-Paket.

4. Snyk Security Scanner (SAST & Open Source Security)

Snyk ist eine führende Sicherheitsplattform zur statischen Code-Analyse (SAST - Static Application Security Testing) und zur Überprüfung von Abhängigkeiten über mehrere Programmiersprachen hinweg.

Snyk CLI Installation & Authentifizierung

# Globale Installation des Snyk CLI via NPM
npm install -g snyk

# Authentifizierung des CLI-Tools mit dem Snyk-Account
snyk auth

Quellcode- & Abhängigkeitsscans mit Snyk

# Quellcode-Analyse (SAST) im aktuellen Projektverzeichnis ausführen
snyk code test

# Quellcode-Analyse für einen spezifischen Pfad ausführen
snyk code test /pfad/zum/code

# Prüfung aller Projekt-Abhängigkeiten (Open Source Vulnerabilities)
snyk test

5. Plattformübergreifende Vulnerability Datenbanken & Scanner (OSV)

• Google OSV (Open Source Vulnerabilities):
  🔗 https://osv.dev
  Eine verteilte Schwachstellendatenbank für Open Source, die Sicherheitslücken über Sprachgrenzen hinweg (Rust/Cargo, NPM, PyPI, Linux/Ubuntu, Go, C/C++) aggregiert.

• osv-scanner CLI Tool:
  Ein von Google bereitgestellter universeller Vulnerability Scanner, der Projekt-Abhängigkeiten direkt gegen die verteilte OSV-Datenbank prüft:

  # Installation des OSV-Scanners (v2)
  go install github.com/google/osv-scanner/v2/cmd/osv-scanner@v2
  
  # Rekursiver Scan aller Projekt-Abhängigkeiten im aktuellen Verzeichnis
  osv-scanner -r .
  
  # Oder rekursiver Scan für einen spezifischen Projektpfad
  osv-scanner -r path/to/your/project
  

Weitere alternative Security Scanner zu OSV-Scanner

Neben OSV-Scanner und Snyk stehen weitere professionelle, plattformübergreifende Open-Source-Scanner bereit:

• Trivy (Aqua Security):
  Ein umfassender Open-Source Scanner für Dateisysteme, Code-Abhängigkeiten (Cargo, NPM, PIP) und Container:

  # Installation unter Ubuntu
  sudo apt install trivy
  
  # Scan des Projektverzeichnisses auf Schwachstellen
  trivy fs /pfad/zum/projekt
  

• Grype (Anchore):
  Ein extrem schneller Vulnerability-Scanner für Quellcode-Verzeichnisse und Software-Stücklisten (SBOMs):

  # Installation via Install-Skript
  curl -sSfL https://raw.githubusercontent.com/anchore/grype/main/install.sh | sh -s -- -b /usr/local/bin
  
  # Scan eines Projektverzeichnisses
  grype dir:/pfad/zum/projekt
  

• Semgrep (SAST Code Scanner):
  Ein leichter, regelbasierter SAST-Scanner für statische Code-Analysen auf Sicherheitslücken:

  # Installation via PIP
  pip install semgrep
  
  # Statischen Code-Scan im Projekt ausführen
  semgrep scan
  

Sicherheitswert-Bewertungsstandards (Severity Rating) vs. OSV

💡 Wichtige Unterscheidung:
Google OSV ist eine Schwachstellendatenbank und ein Vergleichs-Scanner, jedoch kein eigenständiges Sicherheitswert-Bewertungssystem. OSV aggregiert Daten aus Quellen wie NVD (National Vulnerability Database), RustSec und GitHub Security Advisories.

Der eigentliche Sicherheitswert (Severity Score) einer Schwachstelle in OSV, Rust, C oder C++ wird nach internationalen Standards berechnet:

1. CVSS (Common Vulnerability Scoring System, v3.1 / v4.0):
   Quantitativer Sicherheitswert von 0.0 bis 10.0:

   • 0.0 - 3.9: Low (Geringes Risiko)
   • 4.0 - 6.9: Medium (Mittleres Risiko)
   • 7.0 - 8.9: High (Hohes Risiko)
   • 9.0 - 10.0: Critical (Kritisches Risiko)

2. CWE (Common Weakness Enumeration):
   Standardisierte Kategorisierung von Sicherheitsfehler-Klassen (z. B. CWE-119 für Buffer Overflow, CWE-79 für XSS, CWE-416 für Use-After-Free).

3. EPSS (Exploit Prediction Scoring System):
   Prozentuale Wahrscheinlichkeit (0% bis 100%), dass eine Schwachstelle in den nächsten 30 Tagen tatsächlich in freier Wildbahn ausgenutzt wird.

📑 Zusammenfassende Befehlsübersicht für dieses Projekt

| Multi-Language | snyk code test [pfad] | Statische Quellcode-Analyse (SAST) auf Sicherheitslücken | | Multi-Language | snyk test | Scannt Projekt-Abhängigkeiten via Snyk Platform | | Multi-Language | osv-scanner -r . | Scannt Projekt-Abhängigkeiten gegen die verteilte OSV-Schwachstellendatenbank | | Multi-Language | trivy fs /pfad/zum/projekt | Alternative: Open-Source Scanner für Dateisysteme & Abhängigkeiten | | Multi-Language | grype dir:/pfad/zum/projekt | Alternative: Schneller Vulnerability Scanner von Anchore | | Multi-Language | semgrep scan | Alternative: Regelbasierte statische Code-Analyse (SAST) |

wissen-ahrensburg.de (MeinCMS)

CMS mit Wiki-Funktion & Multi-Tenancy (100% Rust Workspace Edition, PostgreSQL).

Architektur & Tech (Rust Workspace)

• meincms_parser/: Hochleistungs Markdown & MediaWiki Parser Crate (mit C-FFI Exporten).
• meincms_web/: Axum 0.7 Webanwendung. Multi-Tenancy via Hostname, Maud Templating, Admin-Auth, No-Cache Middleware.
• meincms_backup/: Backup & Repair CLI Tool (YAML/XML Ex-/Import & Repair).
• meincms_admin/: User & Admin Management CLI Tool (Argon2 Password Hashing).
• Tech: Rust 1.80+, Tokio, Axum, Maud, SQLx, PostgreSQL, Argon2.
• Lizenz: AGPL-3.0.

Befehle (Rust & Qualitätssicherung)

• Workspace Check & Test: cargo check & cargo test --workspace
• Linter & Formatierung: cargo clippy & cargo fmt --check
• Dokumentation (mdBook): npm run build:docs (synchronisiert AGENTS.md & Skills nach docs/src und führt mdbook build docs aus)
• Dokus veröffentlich: npm run ver (baut Dokus inkl. AGENTS.md & Skills und veröffentlicht automatisch via gh-pages)
• Web Backend: cargo run -p meincms_web
• Backup CLI: cargo run -p meincms_backup -- [export|import|repair]
• Admin CLI: cargo run -p meincms_admin

Konventionen & Regeln für KI-Agenten

• Git & Sicherheit: NIEMALS .env oder Passwörter einchecken. !.env.example als Referenz nutzen.
• Produktion / Unix Socket: PostgreSQL-Verbindung bevorzugt über Unix Domain Socket (DATABASE_URL="postgres://user:pass@/var/run/postgresql/meincms"). Webserver via UNIX_SOCKET.
• Mandanten: Multi-Tenancy mit Filterung nach TenantId ("main" = Standard, "doc" = Technik).
• Sicherheit: Markdown & MediaWiki strikt gegen XSS/CSRF sichern, keine Inline-Skripte. No-Cache-Header erzwingen.
• Menschliche Verantwortung & Code-Review: KI-Agenten (CLI & IDE) sind Assistenzwerkzeuge. Die Verantwortung für Code-Sicherheit, Funktion und Wartbarkeit liegt stets beim Menschen. Code muss verständlich strukturiert und dokumentiert werden, damit er nachvollziehbar und optimierbar bleibt.
• Frontend / Maud: Editor-Toggling via Vanilla JS (DOMContentLoaded & style.display), nicht rein über CSS-Klassen.
• Backend: Beim Speichern von Wiki-Artikeln das jeweils nicht genutzte Inhaltsfeld (Markdown/MediaWiki) explizit leeren.
• DB-Modell: WikiArtikel, WikiArtikelVersion, WikiNamespace, WikiCategory.
• Backup & Repair: Nach Import oder Parser-Änderungen stets repair über meincms_backup ausführen.
• Dokumentation & mdBook: Bei Konfigurations- oder Architekturänderungen stets die Doku in docs/ aktualisieren und danach npm run build:docs bzw. mdbook build docs ausführen.

🤖 KI-Agenten, Subagenten, Prompt-Sicherheit & Praxis-Handbuch Vibe Coding

Dieses Kapitel beschreibt die Sicherheitsstrategie für KI-gestützte Entwicklung (Vibe Coding), die menschliche Letztverantwortung bei der Nutzung von KI Agent CLIs und IDEs, die Tiefenarchitektur von AGENTS.md, Subagenten und Skills, maßgebliche Design Patterns & Softwarearchitekturen sowie ein konkretes Praxis-Handbuch für den täglichen Entwicklungsalltag im MeinCMS Workspace.

1. Menschliche Verantwortung vs. KI-Agent (CLI & IDE)

👤 Der Mensch ist verantwortlich – nicht die Maschine!

Ob beim Einsatz von KI Agent CLIs (wie Google Antigravity, Claude Code, Aider) oder KI Agent IDEs (wie Cursor, Windsurf, VS Code KI-Plugins):

• Die KI ist ein Werkzeug (Assistent), kein Entwickler mit Haftung oder Urteilsfähigkeit.
• Die rechtliche, funktionale und sicherheitsbezogene Letztverantwortung liegt ausnahmslos beim menschlichen Entwickler!
• Die Maschine halluziniert, übersieht Edge Cases oder wählt veraltete Muster, wenn sie nicht strikt geleitet und überprüft wird.

flowchart LR
    A["Menschlicher Entwickler\n(Konzeption, Verantwortung & Governance)"] -->|1. Prompting & Regelerteilung| B["KI Agent CLI / IDE\n(Code-Generierung & Vorschläge)"]
    B -->|2. Entwurf & Diff| C["Menschliches Code Review\n& Verstehen des Codes"]
    C -->|3. Qualitätsgate| D["Automatische Tests & Audits\n(cargo check, clippy, audit)"]
    D -->|4. Freigabe| E["Produktions-Codebase"]

    style A fill:#d7ffd9,stroke:#388e3c
    style B fill:#e1f5fe,stroke:#0288d1
    style C fill:#fff9c4,stroke:#fbc02d
    style D fill:#f3e5f5,stroke:#ab47bc
    style E fill:#e8f5e9,stroke:#2e7d32

🧠 Verstehen, was programmiert wird – Das Vibe-Coding-Dilemma

Ein zentraler Grundsatz der Softwareentwicklung mit KI lautet:

⚠️ Wer Code nicht versteht, kann ihn später weder warten, verbessern, refaktorieren noch von Sicherheitslücken befreien!

Blindes "Vibe Coding" (einfaches Akzeptieren von KI-Vorschlägen ohne Durchlesen und Verstehen):

1. Erzeugt technische Schulden (Technical Debt): Es entsteht unübersichtlicher "Spaghetticode", der unnötig komplex ist.
2. Erschwert spätere Anpassungen: Wenn ein Bug auftritt oder eine Funktion erweitert werden muss, versteht niemand mehr, warum die KI bestimmte Variablen oder Pfade gewählt hat.
3. Führt zu verdeckten Sicherheitslücken: Unsichere C-ABI Speicherzugriffe, fehlendes HTML-Escaping oder falsche Datenbankschlüssel bleiben unbemerkt.

Verpflichtende Entwickler-Regel:

• Vor dem Committen muss der Entwickler den von der KI generierten Code Zeile für Zeile durchlesen.
• Bei unklaren Abschnitten ist die KI aufzufordern: "Erkläre mir schrittweise, was dieser Codeblock tut und warum dieses Muster gewählt wurde."

2. Architektur der KI-Steuerung: AGENTS.md, Subagenten & Skills

Um sicherzustellen, dass unterschiedliche KI-Agenten konsistenten, sicheren und architekturkonformen Code schreiben, nutzt das Projekt ein dreistufiges Steuerungssystem:

graph TD
    A["AGENTS.md\n(Globale Regeln & Workspace-Kontext)"] --> B["Subagenten\n(Spezialisierte Agenten-Instanzen)"]
    A --> C["Skills (.agents/skills/)\n(Modulares Domänenwissen & Workflows)"]
    B -->|Nutzt| C

📄 1. AGENTS.md (Das zentrale Regelwerk)

AGENTS.md ist die Ankerdatei für jeden KI-Agenten im Workspace. Sie wird bei jedem Agentenstart automatisch in den Systemkontext geladen.

• Inhalt: Technologie-Stack (Rust, Axum, Maud, PostgreSQL), Sicherheitsregeln (XSS-Schutz, Unix Sockets, .env-Sperren), Befehle für Qualitätssicherung (cargo check, npm run build:docs).
• Zweck: Stellt sicher, dass kein Agent projektfremde Frameworks (wie TailwindCSS ohne Absprache) oder unsichere Praktiken einführt.

🤖 2. Subagenten (Isolierte Spezialisierungen)

Ein Subagent ist eine eigenständige KI-Instanz, die für eine spezifische Teilaufgabe (z. B. Recherche, Datenbankabfragen, UI-Building) aufgerufen wird.

• Vorteile:
  • Context Isolation: Der Hauptagent bleibt übersichtlich und wird nicht mit tausenden Zeilen Analyse-Log überflutet.
  • Least Privilege: Ein Research-Subagent erhält nur Lese-Rechte (view_file, grep_search), während ein Worker-Subagent Schreibrechte besitzt.
  • Fokussierte Systemprompts: Ein db_admin-Subagent kennt primär SQLx- und PostgreSQL-Konventionen.

🛠️ 3. Skills (.agents/skills/)

Skills sind modulare Ordner mit detaillierten Handbüchern (SKILL.md), Hilfsskripten und Referenzbeispielen.

• Ordnerstruktur:

  .agents/skills/
  ├── admin_manager/   # User-Management CLI Expertenwissen
  ├── backup_manager/  # YAML/XML Ex-/Import & Repair Expertenwissen
  ├── db_admin/        # SQLx & PostgreSQL Expertenwissen
  ├── meincms_worker/  # Rust Workspace & Webserver Entwickler
  ├── parser/          # meincms_parser C-FFI & Markdown Compiler
  └── ui_worker/       # Maud Templating, Vanilla JS & CSS
  

• Aufbau einer SKILL.md: Enthält YAML-Frontmatter (name, description) sowie Schritt-für-Schritt-Anleitungen für komplexe Operationen.

3. LLM- & Kontext-Sicherheitslücken (OWASP Top 10 for LLMs)

Beim Einsatz von Sprachmodellen und autonomen Agenten müssen folgende Hauptschwachstellen abgewehrt werden:

flowchart TD
    A["Benutzereingabe / Externe Datei"] -->|1. Prompt Injection / Context Poisoning| B["KI-Agent / Sprachmodell"]
    B -->|2. Insecure Output / Code Generation| C["Quellcode / Terminal-Befehl"]
    C -->|3. Automatische Ausführung| D["System & Datenbank"]
    
    style A fill:#ffcccc,stroke:#ff0000
    style B fill:#e1f5fe,stroke:#0288d1
    style C fill:#fff9c4,stroke:#fbc02d
    style D fill:#d7ffd9,stroke:#388e3c

1. Prompt Injection (Direkt & Indirekt)

• Direkt: Ein Angreifer versucht über die Benutzeroberfläche oder Formularingaben den KI-Systemprompt zu überschreiben.
• Indirekt: Bösartiger Text befindet sich in verarbeiteten Wiki-Artikeln, Markdown-Dateien oder extern abgerufenen Webseiten (read_url_content), um den KI-Agenten während der Analyse zu manipulieren.
• Abwehr: Strikte Trennung von Systeminstruktionen und Daten-Kontext. Keine Ausführung von Anweisungen aus unvertrauten Inhalten ohne Validierung.

2. Context Poisoning (Kontext-Vergiftung)

• Manipulierte Quelldateien oder Repositories injizieren gefälschte Regeln oder schädlichen Code in den Arbeitskontext des Agenten.
• Abwehr: Immutable Konfigurationsdateien (AGENTS.md, .env.example) und schreibgeschützte Validierungsregeln.

3. Sensitive Data Exposure (Datenabfluss im Prompt)

• Auslesen von Passwörtern, .env-Dateien oder API-Keys in den Modell-Kontext.
• Abwehr: .env und vertrauliche Dateien sind in .gitignore eingetragen. Webserver blockiert den Zugriff auf Konfigurationspfade mit HTTP 403.

4. Design Patterns & Softwarearchitektur für Multi-Agenten-Systeme

Wenn mehrere KI-Agenten oder unterschiedliche Entwickler an einem Projekt arbeiten, muss die Softwarearchitektur kristallklar, streng typisiert und deterministisch sein.

graph TD
    subgraph Architektonische Entwurfsmuster für KI-Systeme
        DP1["1. Orchestrator-Worker Pattern\n(Klare Aufgabenverteilung)"]
        DP2["2. Explicit Contract & Strong Typing\n(Rust Traits, C-ABI Header)"]
        DP3["3. Single Source of Truth (SSOT)\n(Zentrale Schemas & Datentypen)"]
        DP4["4. Quality Gate & Sandbox Pattern\n(Automatische Linter & Scans)"]
        DP5["5. Self-Documenting Architecture\n(Modul-Grenzen & Inline-Doku)"]
    end

🧱 Pattern 1: Orchestrator-Worker Pattern (Hierarchische Delegation)

• Problem: Ein einzelner Agent verliert bei großen Tasks den Überblick oder überschreitet Kontextgrenzen.
• Lösung: Der Hauptagent fungiert als Orchestrator (Plant Schritte, verteilt Aufgaben). Subagenten führen klar begrenzte Einzelaufgaben aus und liefern strukturierte Ergebnisse zurück.

📜 Pattern 2: Explicit Contract & Strong Typing Pattern

• Problem: KI-Agenten neigen in dynamischen Sprachen (wie JavaScript oder Python) zu Annahmen über Objektstrukturen ("Magic Objects"), was zu Laufzeitfehlern führt.
• Lösung in Rust: Nutzung von Rusts striktem Typensystem (struct, enum, Option<T>, Result<T, E>). Typfehler werden direkt vom Compiler abgefangen (cargo check), sodass halluzinierter Code gar nicht erst kompilierbar ist. Bei C-FFI Schnittstellen gibt ein C-Header (meincms_parser.h) exakte Verträge vor.

📌 Pattern 3: Single Source of Truth (SSOT)

• Problem: KI-Agenten erstellen doppelte Typdefinitionen oder widersprüchliche Konfigurationslogiken an verschiedenen Orten.
• Lösung: Zentrale Datenmodelle in vertrauenswürdigen Quelldateien (z. B. WikiArtikel in SQLx/Rust). Konfigurationen ausschließlich in .env.example.

🛡️ Pattern 4: Quality Gate & Defensive Sandbox Pattern

• Problem: KI-generierter Code könnte unbemerkt Sicherheitslücken (wie unsafe-Missbrauch in Rust oder Pufferüberläufe in C) einschleusen.
• Lösung: Jede Codeänderung muss ein unbestechliches Testgate durchlaufen. CLI-Agenten führen automatisch Linter (cargo clippy), Sicherheitsscans (cargo audit, flawfinder) und Formatter (cargo fmt) aus.

📖 Pattern 5: Self-Documenting & Explainable Architecture

• Problem: Zukünftige KI-Agenten verstehen verschachtelte Logik ohne Dokumentation nicht korrekt und generieren fehlerhafte Refactorings.
• Lösung: Jedes Modul besitzt klare Dokumentationskommentare (/// in Rust) und Architekturbeschreibungen in docs/src.

5. Vibe Coding Absichern in den Kernsprachen (C, C++, Rust, JavaScript)

KI-generierter Code wird vor der Übernahme in das Repository sprachspezifischen Sicherheitsprüfungen unterzogen:

🔴 C & C++ (Speicher- & C-ABI-Sicherheitsbewertung)

Beim Generieren von C-Code oder C-ABI Exporten (meincms_parser.h):

🦀 Rust (Typensicherheit & Unsafe-Analyse)

Rust bietet durch den Ownership-Borrow-Checker von Haus aus höchste Speichersicherheit. Bei KI-Code muss insbesondere die Verwendung von unsafe überwacht werden:

💛 JavaScript & Node.js (Web- & Dependency-Sicherheit)

Bei KI-generiertem Frontend-Code oder Node.js-Skripten:

6. Automatisiertes Test- & Review-Gate für KI-Code

Jeder durch KI-Agenten generierte oder modifizierte Code muss folgendes Prüfgate durchlaufen:

# 1. Rust Workspace & Typenprüfung
cargo check
cargo test --workspace

# 2. Linter & Formatierung
cargo clippy
cargo fmt --check

# 3. Sicherheits- & Abhängigkeits-Audits
cargo audit
npm audit
osv-scanner -r .

# 4. Dokumentation bauen & mdBook aktualisieren
npm run build:docs

7. 📘 Praxis-Handbuch: Vibe Coding im Entwickler-Alltag

Vibe Coding bedeutet nicht, die Kontrolle abzugeben, sondern menschliche Intuition, Produktstrategie und Qualitätskontrolle mit der rasenden Geschwindigkeit generativer KI zu verschmelzen.

7.1 Der 5-Stufen-Workflow für sicheres Vibe Coding

flowchart TD
    S1["1. Task & Context Prep\n(AGENTS.md & Ziel definieren)"] --> S2["2. Spec-First & Micro-Prompting\n(Kleine Schritte, klare Constraints)"]
    S2 --> S3["3. Interactive Diff-Review\n(Zeile-für-Zeile Code verstehen)"]
    S3 --> S4["4. Local Quality Gate\n(cargo check / test / clippy)"]
    S4 --> S5["5. Doc-Sync & Commit\n(npm run build:docs & Git)"]

Stufe 1: Kontext & Vorbereitung (Context Prep)

• Ziel: Die KI mit den notwendigen Informationen versorgen, ohne ihren Kontextfenster mit unnötigem Code zu überladen.
• Praxis-Aktion: Verweise explizit auf bestehende Moduldateien oder nutze Subagenten-Skills (z. B. .agents/skills/ui_worker/SKILL.md), statt der KI freie Hand zu lassen.
• Beispiel: "Lies meincms_web/src/routes/wiki.rs bevor du eine neue Route hinzufügst."

Stufe 2: Spec-First & Micro-Iteratives Prompting

• Ziel: Halluzinationen und gigantische, unüberschaubare Diffs vermeiden.
• Praxis-Aktion: Zerlege komplexe Features in atomare Schritte (Interface/Struct -> Datenbankschicht -> Web-Handler -> Maud UI -> Frontend JS).
• Regel: Lass die KI erst Datenstrukturen (struct, enum) oder Methodensignaturen vorschlagen und bestätige diese, bevor der Rumpf implementiert wird.

Stufe 3: Interaktives Code-Review (Pair-Programming-Modus)

• Ziel: Vollständiges Verständnis des geschriebenen Codes sichern.
• Praxis-Aktion: Akzeptiere NIEMALS blind Code, den du nicht verstehst. Nutze Rückfragen an die KI:
  • "Warum verwendest du hier tokio::spawn statt eines direkten Async-Calls?"
  • "Welche Edge Cases entstehen, wenn tenant_id leer ist?"
  • "Stelle sicher, dass kein unsafe-Block ohne explizite Begründung eingefügt wird."

Stufe 4: Lokales Quality Gate & Verifikation

• Ziel: Sofortige Rückmeldung über Syntax-, Typ- oder Linter-Fehler.
• Praxis-Aktion: Lass das automatische Qualitätssicherungs-Gate im Terminal ausführen:
  • cargo check (Prüft Rust-Typen & Kompilierbarkeit)
  • cargo test --workspace (Führt alle Unit- & Integrationstests aus)
  • cargo clippy (Prüft Idiomatik & Performancelücken)

Stufe 5: Dokumentation & Commit

• Ziel: Nachhaltigkeit des Quellcodes und Synchronität des Handbuchs.
• Praxis-Aktion: Führe npm run build:docs aus, um die mdBook-Dokumentation zu aktualisieren, und erstelle einen aussagekräftigen Git-Commit.

8. 💻 Konkrete Praxisbeispiele im MeinCMS Workspace

Im Folgenden werden vier praxisnahe Szenarien aus dem MeinCMS Entwicklungsalltag Schritt für Schritt demonstriert.

8.1 Praxisbeispiel A: Neue Web-Funktion im Axum/Maud-Stack

Aufgabenstellung: Hinzufügen einer Revisions-Vergleichsansicht (Diff-View) in meincms_web.

1. Praxis-Prompt an den KI-Agenten:

Wir möchten in 'meincms_web' eine neue Route 'GET /wiki/:title/diff' hinzufügen.
- Nutze Axum 0.7 und Maud Templating.
- Filtere strikt nach TenantId über den Hostname-Extractor (Multi-Tenancy).
- Die HTML-Ausgabe muss den XSS-Regeln entsprechen (Maud escapt Variablen automatisch, nutze kein PreEscaped für User-Inhalte).
- Erstelle dazu das Maud-Template in 'meincms_web/src/views/diff.rs' und binde es in 'routes.rs' ein.
- Gib mir zuerst die Signatur des Handlers und das Datenmodell für den Revisions-Vergleich zur Freigabe.

2. Interaktives Code-Review des Entwicklers:

Der Entwickler prüft den von der KI generierten Handler-Code:

#![allow(unused)]
fn main() {
// MEINCMS SAFETY REVIEW: TenantId muss zwingend in der SQL-Query vorkommen!
pub async fn wiki_diff_handler(
    Host(host): Host,
    State(pool): State<PgPool>,
    Path(title): Path<String>,
) -> Result<Markup, WebError> {
    let tenant_id = extract_tenant_id(&host);
    let artikel = sqlx::query_as!(
        WikiArtikel,
        "SELECT * FROM wiki_artikel WHERE title = $1 AND tenant_id = $2",
        title,
        tenant_id
    )
    .fetch_one(&pool)
    .await?;

    Ok(views::diff::render_diff(&artikel))
}
}

• Review-Urteil: ✅ Tenant-Filter vorhanden, Maud-Rückgabetyp korrekt, SQLx Compile-Time Query Safety genutzt.

8.2 Praxisbeispiel B: Parser-Erweiterung (meincms_parser) & C-FFI Sync

Aufgabenstellung: Hinzufügen einer neuen Hinweisbox-Syntax (:::info ... :::) im Markdown-Compiler mit C-FFI Export.

1. Praxis-Prompt an den KI-Agenten:

Erweitere das Crate 'meincms_parser' um die Unterstuetzung von Info-Boxen (':::info').
- Passe den Rust-AST und den Markdown-Parser an.
- Stelle sicher, dass die C-FFI Schnittstelle 'meincms_parse_markdown' in 'meincms_parser.h' weiterhin ABI-kompatibel bleibt.
- Speicher muss durch den Aufrufer zwingend über 'meincms_free_string()' freigegeben werden.
- Schreibe einen Rust Unit-Test in 'meincms_parser/tests/parser_tests.rs'.

2. Verifikation im Terminal:

cargo test -p meincms_parser
flawfinder meincms_parser/

8.3 Praxisbeispiel C: Gezieltes Bugfixing & Fehlerdiagnostik

Aufgabenstellung: Behebung eines Fehlers, bei dem Sonderzeichen im Artikelnamen zu 404-Fehlern führen.

1. Analytischer Bugfix-Prompt (Keine voreilige Code-Generierung):

Symptom: Artikel mit Umlauten (z. B. 'Über uns') erzeugen beim Aufruf in 'meincms_web' einen HTTP 404 Fehler.
Eingrenzung: Siehe 'meincms_web/src/routes/wiki.rs' und 'meincms_parser/src/slug.rs'.
Aufgabe: Analysiere den URL-Decoding-Schritt und das Slug-Building. 
Nenne mir die 2 wahrscheinlichsten Ursachen und zeige mir den exakten Diff, der das Problem behebt. Ändere vorerst keine anderen Dateien.

2. Nachvollziehen der Ursache:

Die KI identifiziert, dass percent_encoding::percent_decode_str gefehlt hat, bevor der Title-Lookup an PostgreSQL übergeben wurde. Der Entwickler bestätigt die Änderung nach Durchsicht des Diffs.

8.4 Praxisbeispiel D: Datenbank-Migration & Multi-Tenancy Audit

Aufgabenstellung: Hinzufügen eines Feldes read_count zu Artikeln.

1. Praxis-Prompt:

Erstelle eine neue SQLx Migration: 'ALTER TABLE wiki_artikel ADD COLUMN read_count BIGINT NOT NULL DEFAULT 0;'.
Aktualisiere die Struct 'WikiArtikel' im Web-Crate und im Backup-Tool ('meincms_backup').
Stelle sicher, dass 'cargo run -p meincms_backup -- repair' ohne Fehler durchläuft.

2. Ausführung des Repair-Tests:

cargo run -p meincms_backup -- repair

9. 📋 Praxis-Checkliste für Entwickler (Do's and Don'ts)

10. 📝 Praxis-Prompt-Templates für den täglichen Einsatz

Nutze diese Vorlagen direkt in deiner KI Agent CLI oder IDE:

🎯 Template 1: Neues Feature entwickeln (Rust / Axum / Maud)

PROMPT TEMPLATE: FEATURE-ENTWICKLUNG
Rolle: Du bist ein senior Rust-Entwickler für das MeinCMS Workspace.
Aufgabe: Implementiere [FEATURE BESCHREIBUNG].
Randbedingungen:
- Crate: [meincms_web / meincms_parser / meincms_backup]
- Web/UI: Axum 0.7, Maud Templating, Vanilla JS (keine Inline-Skripte), kein TailwindCSS.
- Sicherheit: XSS-Schutz durch Maud, Multi-Tenancy Filterung auf tenant_id.
Vorgehen:
1. Zeige mir zuerst die geplante Modulstruktur und Struct-Definitionen.
2. Nach meiner Freigabe erstelle den Code in kleinen, verständlichen Blöcken.

🔍 Template 2: Code-Review & Security Audit Prompt

PROMPT TEMPLATE: CODE REVIEW & SECURITY AUDIT
Rolle: Du bist ein Security & Rust Audit Expert.
Aufgabe: Überprüfe folgenden Code-Abschnitt in [DATEINAME]:
[CODE SNIPPET ODER DATEIPFAD]
Prüfpunkte:
1. Gibt es potenzielle Speichersicherheits-Lücken oder unbegründete 'unsafe'-Blöcke?
2. Ist Multi-Tenancy (TenantId Isolation) in allen Datenbankschritten garantiert?
3. Werden Benutzereingaben korrekt geescapet?
4. Gibt es unbehandelte Errors (Panics / unwraps)?
Gib dein Feedback strukturiert mit konkreten Verbesserungsvorschlägen aus.

🛠️ Template 3: Bugfix & Root-Cause-Analysis Prompt

PROMPT TEMPLATE: BUGFIXING & DIAGNOSE
Symptom: [FEHLERBESCHREIBUNG UND LOG-AUSZUG]
Betroffene Dateien: [DATEIPFADE]
Aufgabe:
1. Analysiere das Problem und nenne mir die Ursache (Root Cause).
2. Schlage maximal 2 Lösungswege vor und vergleiche Vor- und Nachteile.
3. Ändere noch KEINEN Code, sondern warte auf meine Entscheidung.

🧹 Template 4: Refactoring & Architecture Cleanup Prompt

PROMPT TEMPLATE: REFACTORING
Ziel: Refaktoriere den Code in [DATEINAME], um die Lesbarkeit und Wartbarkeit zu erhöhen.
Regeln:
- Ändere KEINE externen Funktionssignaturen oder Verhalten (No Breaking Changes).
- Halte dich strikt an die Design Patterns in 'docs/src/architektur_design_patterns.md'.
- Optimiere Fehlerbehandlung (verwende Result/Option statt unwrap).
- Erstelle nach dem Refactoring Unit Tests zur Absicherung.

tierung cargo clippy cargo fmt --check

3. Sicherheits- & Abhängigkeits-Audits

cargo audit npm audit osv-scanner -r .

4. Dokumentation bauen & mdBook aktualisieren

npm run build:docs

🚀 AGY CLI & AGY IDE: Praxis-Workflow, Einstellungen & Token-Optimierung

Herzlich willkommen im Praxis-Handbuch für die Arbeit mit Google Antigravity (AGY) im MeinCMS Workspace. Dieses Kapitel zeigt dir, wie du die AGY CLI (agy), die AGY IDE und Antigravity 2.0 optimal konfigurierst, deinen Entwicklungs-Workflow beschleunigst und den Token-Verbrauch drastisch reduzierst.

🧭 Übersicht & Unterkapitel

Um die Dokumentation übersichtlich zu halten, ist dieses Thema in drei vertiefende Praxis-Guides unterteilt:

graph TD
    A["AGY Praxis- & Performance-Handbuch"] --> B["⚙️ 1. AGY CLI & IDE Setup\n(docs/src/agy_workflow/cli_ide_setup.md)"]
    A --> C["⚡ 2. Token- & Speed-Tutorial\n(docs/src/agy_workflow/token_speed_optimization.md)"]
    A --> D["🤝 3. Mensch & KI Teamwork\n(docs/src/agy_workflow/human_ai_collaboration.md)"]

    style A fill:#e1f5fe,stroke:#0288d1
    style B fill:#d7ffd9,stroke:#388e3c
    style C fill:#fff9c4,stroke:#fbc02d
    style D fill:#f3e5f5,stroke:#ab47bc

📄 1. Schritt-für-Schritt Setup & Konfiguration: AGY CLI & IDE

• Inhalt: Installation, settings.json, Terminal-Sandbox, Berechtigungen (Allowlists), die 3 Interaktionsmodi der IDE (Tab Autocomplete, Inline Ctrl+I, Sidebar Agent Mode) sowie Antigravity 2.0 Workspace-Rechte.

⚡ 2. Tutorial: KI-Geschwindigkeit maximieren & Token-Verbrauch senken

• Inhalt: Vermeidung von Context Flooding, .aiignore & .geminiignore Konfiguration, gezieltes @-Mentioning, Subagenten-Isolation, Modellwahl (Flash vs. Pro) und konkrete Tricks für minimale Antwortzeiten und minimale Token-Kosten.

🤝 3. Mensch & KI als Team: Augmented Engineering statt Weg-Rationalisierung

• Inhalt: Warum das Ersetzen von Entwicklern durch reine KI zu Systemkollaps führt, die Symbiose aus Mensch (Architekt/Pilot) und KI (Co-Pilot), Human-in-the-Loop Prinzipien, Verantwortungskultur und Argumentationshilfen für Entwickler gegenüber dem Management.

🎯 Warum ist Workflow- & Token-Optimierung wichtig?

Ein unkonfigurierter KI-Agent kann schnell träge werden, wenn er bei jeder Frage das gesamte Repository scannen muss oder gigantische Log-Dateien in den Kontext lädt.

🔗 Direkt zu den Anleitungen:

• 👉 Weiter zu Kapitel 9.1: AGY CLI & IDE Setup & Konfiguration
• 👉 Weiter zu Kapitel 9.2: Tutorial für maximale KI-Geschwindigkeit & Token-Sparsamkeit
• 👉 Weiter zu Kapitel 9.3: Mensch & KI als Team (Augmented Engineering)

⚙️ Schritt-für-Schritt Setup & Konfiguration: AGY CLI & AGY IDE

Dieses Kapitel führt dich schrittweise durch die optimale Einrichtung von Google Antigravity (AGY) in der Konsole (AGY CLI agy), der AGY IDE (VS Code-basiert) und der Antigravity 2.0 Desktop-App.

1. AGY CLI (agy) – Terminal Setup & Einstellungen

Die AGY CLI ist das schnelle, leichtgewichtige Terminal-Interface für Entwickler.

🚀 Starten & Beenden

• Starten: Befehl agy im Projekt-Stammverzeichnis ausführen.
• Beenden: Tastenkombination Ctrl+D Ctrl+D drücken oder /exit eingeben.
• Hilfe aufrufen: /help im TUI-Chat eingeben oder agy --help im Terminal.

⚙️ Konfigurationsdatei ~/.gemini/antigravity-cli/settings.json

Die Einstellungen für die CLI werden zentral in der Datei ~/.gemini/antigravity-cli/settings.json verwaltet. Hier ist eine optimierte Praxis-Konfiguration für den MeinCMS Workspace:

{
  "model": "gemini-3.5-flash",
  "terminalSandbox": true,
  "toolExecutionPolicy": "request-review",
  "permissionGrants": {
    "command": [
      "cargo check",
      "cargo test",
      "cargo clippy",
      "npm run build:docs"
    ],
    "read_file": [
      "/home/thorsten/wissen-ahrensburg.de"
    ]
  },
  "browserAllowlist": [
    "localhost",
    "127.0.0.1",
    "github.com",
    "docs.rs"
  ]
}

Erläuterung der wichtigsten Einstellungen:

• model: Standard-Modell für schnelle Antworten (gemini-3.5-flash für Tempo, pro für komplexe Refactorings).
• terminalSandbox: Ausführung aller Terminal-Befehle in einer isolierten Sandbox (Schutz vor ungewollten Systemänderungen).
• toolExecutionPolicy: "request-review" erfordert Entwickler-Bestätigung bei schreibenden/ausführenden Befehlen.
• permissionGrants: Erlaubt häufig genutzte Lese- und Test-Befehle ohne wiederholte Bestätigungsaufforderungen.

2. AGY IDE – Die 3 Interaktionsmodi im Überblick

Die AGY IDE integriert Agenten-Workflows direkt in den Editor. Je nach Aufgabe wählst du den passenden Interaktionsmodus:

graph LR
    A["AGY IDE Modaliäten"] --> B["1. Passive Mode\n(Tab Autocomplete)"]
    A --> C["2. Instruktiver Mode\n(Inline Ctrl+I)"]
    A --> D["3. Kollaborativer Mode\n(Sidebar Agent Chat)"]

A. Passiver Modus: Tab Autocomplete & Supercomplete

Ideal für schnelles Tippen, automatische Importe und Navigation.

• Autocomplete: Schlägt Code direkt an der Cursor-Position vor.
• Supercomplete: Schlägt größere Diffs (inkl. Löschungen und Refactorings) in schwebenden Fenstern vor.
• Tab-to-Jump: Antizipiert die nächste Navigationsstelle im Code – drücke <tab>, um dorthin zu springen.
• Tab-to-Import: Fügt fehlende use-Statements in Rust oder require/import in JS automatisch am Dateianfang ein.
• Steuerung:
  • <tab>: Vorschlag akzeptieren.
  • <esc>: Vorschlag verwerfen.
  • Ctrl + -> (Linux/Windows) / Cmd + -> (macOS): Vorschlag wortweise akzeptieren.

B. Instruktiver Modus: Inline Command (Ctrl+I / Cmd+I)

Ideal für punktuelle Änderungen an bestehendem Code, ohne den Kontext des Haupt-Chats zu belasten!

1. Markiere einen Codeblock im Editor.
2. Drücke Ctrl+I (bzw. Cmd+I).
3. Gib eine gezielte Anweisung ein (z. B. "Füge Dokumentationskommentare hinzu" oder "Refaktoriere dieses match-Statement").
4. Vorteil: Verbraucht extrem wenige Token, da nur der markierte Block verarbeitet wird.

C. Kollaborativer Modus: Sidebar Chat & Agent Mode

Ideal für komplexe, mehrstufige Aufgaben, Feature-Entwicklung und Architekturfragen.

• Sidebar Chat: Diskussion, Planung und Fragen zum Codebase.
• Agent Mode: Autonomer Pair-Programmer, der Dateien liest/schreibt, Terminal-Befehle ausführt und Tests validiert.
• Inline Code Lenses: Buttons über Funktionen/Structs (z. B. "Refactor", "Write Tests"), um Agenten-Aktionen direkt an Symbolen auszulösen.
• Diagnostic Auto-Fix: Klicke bei Compiler-Warnungen oder Clippy-Fehlern auf "Auto-Fix with Agent".

3. Antigravity 2.0 & Rechteverwaltung (Permissions)

In Antigravity 2.0 kannst du globale und projektbezogene Sicherheitseinstellungen konfigurieren:

🛡️ Tool Execution Policies

• always-proceed: Befehle werden automatisch ohne Rückfrage ausgeführt (nur in sicheren Test-Umgebungen empfohlen).
• request-review: Der Entwickler muss jeden Terminal-Befehl vor Ausführung manuell freigeben (Standard & Empfohlen).
• proceed-in-sandbox: Befehle laufen automatisch in einer isolierten Linux-Unshare/Docker-Sandbox.
• strict: Schreibende Operationen sind deaktiviert.

📁 Datei- & Netzwerk-Zugriffsregeln

• Non-Workspace File Access: Blockiert den Zugriff auf Dateien außerhalb von /home/thorsten/wissen-ahrensburg.de (deny).
• Internet Access Policy: Beschränkt Web-Suchen und URL-Retrieval (read_url_content) auf freigegebene Doku-Domains.
• Command Denylist: Befehle wie rm -rf / oder git push --force sind strikt verboten.

➡️ Nächster Schritt: Weiter zum Token- & Speed-Optimierungs-Tutorial (Kapitel 9.2)

⚡ Tutorial: KI-Geschwindigkeit maximieren & Token-Verbrauch drastisch senken

Dieses Tutorial zeigt dir Schritt für Schritt, wie du Google Antigravity (AGY) extrem schnell machen kannst (Antwortzeiten von 3–5 Sekunden) und gleichzeitig den Token-Verbrauch um bis zu 85% reduzierst.

🛑 1. Das Problem: Warum wird die KI langsam und teuer?

Wenn KI-Agenten in großen Repositories arbeiten, tritt häufig Context Flooding (Kontext-Überflutung) auf:

flowchart TD
    A["Riesiges Repository / Ungefilterter Chat"] --> B["Agent liest ungewollt target/, node_modules/ & Logdateien"]
    B --> C["Kontextfenster überfüllt (100k+ Token pro Prompt)"]
    C --> D["🔴 Hohe Latenz (30s+ Warten) & Hohe Token-Kosten"]
    C --> E["🔴 KI verliert den Faden & halluziniert"]

Hauptursachen für hohen Token-Verbrauch:

1. Ungefiltertes Dateilisten: Die KI durchsucht kompilierte Ordner (target/, node_modules/, docs/book/).
2. Riesige Terminal-Outputs: Kompilier-Logs mit 50.000 Zeilen werden ungeschnitten in den Chat gepostet.
3. Schwammige Prompts: "Überprüfe das Projekt" zwingt die KI, das ganze Repository einzulesen.
4. Falsche Modellwahl: Nutzung von Großmodellen (Pro) für triviale Syntax-Prüfungen.

🛠️ 2. Schritt-für-Schritt Anleitung zur Performance-Optimierung

Mit den folgenden 6 Schritten optimierst du die Geschwindigkeit und Effizienz deines Entwicklungs-Workflows:

Schritt 1: Das Ausschlussdateien-Triplett konfigurieren (.aiignore, .geminiignore, .gitignore)

Erstelle oder aktualisiere die .aiignore und .geminiignore Dateien im Projektstammverzeichnis, um schwere Build-Artefakte und temporäre Ordner vom Agenten-Kontext auszuschließen:

# .aiignore & .geminiignore für MeinCMS
target/
node_modules/
docs/book/
.git/
*.log
*.tmp
.env

• Effekt: Die KI ignoriert Binärdateien und Abhängigkeiten komplett. Token-Ersparnis: ~60%.

Schritt 2: Gezieltes @-Mentioning statt allgemeiner Fragen

Nutze in der AGY IDE oder Antigravity 2.0 das @-Symbol, um exakt die benötigten Dateien an die Nachricht anzuhängen:

• ❌ Schlecht: "Wo werden die Artikel-Routen verarbeitet?" (Agent durchsucht den gesamten Ordner).

• ✅ Gut: "Analysiere @file:meincms_web/src/routes/wiki.rs und erkläre mir die Handler-Funktion."

• Effekt: Der Agent liest nur diese eine Datei ein. Token-Ersparnis: ~80%.

Schritt 3: Subagenten zur Kontext-Isolation einsetzen (invoke_subagent)

Nutze Subagenten für lange Recherche- oder Diagnoseaufgaben. Ein Subagent arbeitet in einer separaten Konversation und liefert nur das Ergebnis zurück:

sequenceDiagram
    participant Hauptagent as Hauptagent (Schlanker Kontext)
    participant Subagent as Subagent (Research)
    Hauptagent->>Subagent: Durchsuche DB-Schemata & erstelle Zusammenfassung
    Note over Subagent: Liest 50 Dateien (100k Token)
    Subagent-->>Hauptagent: Einzeiliges Ergebnis: "Nutze tenant_id Feld in Table X"
    Note over Hauptagent: Kontext bleibt sauber!

• Praxis-Tipp: Delegiere mit /invoke_subagent oder nutze den research Subagenten für Code-Analysen.

Schritt 4: Das richtige Modell für die Aufgabe wählen

Wechsle das Modell in den Einstellungen (settings.json oder Dropdown in Antigravity 2.0):

Schritt 5: Terminal-Output im Prompt begrenzen

Achte darauf, dass Terminal-Ausgaben nicht den Kontext überfluten:

• ❌ Schlecht: cat debug.log (Gibt 10.000 Zeilen im Terminal aus).
• ✅ Gut: cargo check -p meincms_web oder git log -n 5.

Schritt 6: Slash Commands nutzen (/plan, /goal, /schedule)

Verwende integrierte Slash-Commands für strukturierte Arbeitsabläufe:

• /plan: Stoppt die KI vor der Code-Generierung und zwingt sie, zuerst einen knappen Schritt-für-Schritt-Plan zu erstellen.
• /goal: Für autonome, tiefe Tasks über Nacht oder längere Zeiträume.
• /schedule: Erstellt getimerte Hintergrundeinheiten, ohne die Entwickler-Session zu blockieren.

📊 3. Vorher-/Nachher-Vergleich

📋 4. Entwickler-Schnell-Checkliste für maximales Tempo

Vergewissere dich vor jedem großen Task:

• Ist .aiignore vorhanden und schließt target/ sowie node_modules/ aus?
• Habe ich konkrete Dateien per @file: referenziert?
• Nutze ich Gemini Flash für Standard-Aufgaben?
• Ist für punktuelle Änderungen Inline Ctrl+I statt des Haupt-Chats gewählt?
• Habe ich bei großen Recherchen einen Subagenten eingesetzt?

🤝 Mensch & KI-Agenten als Team: Augmented Engineering statt Weg-Rationalisierung

Dieses Kapitel behandelt den Kultur- und Paradigmenwechsel bei der Arbeit mit KI-Agenten wie Google Antigravity (AGY CLI & AGY IDE). Es zeigt auf, warum der Versuch von Unternehmen, Entwickler durch KI zu "weg-zurationalisieren", scheitern muss und wie eine echte Symbiose aus Mensch und KI (Augmented Engineering) zu nachhaltigem Erfolg führt.

🛑 1. Das Industrie-Missverständnis: "Weg-Rationalisierung" von Entwicklern

In vielen Unternehmen und Chefetagen herrscht die irrige Annahme, KI-Agenten dienten primär dazu, Entwickler-Personal einzusparen oder komplett zu ersetzen. Diese Denkweise führt in der Praxis zu verheerenden Konsequenzen:

flowchart TD
    A["Unternehmen versucht Entwickler durch reine KI zu ersetzen"] --> B["Blindes Akzeptieren von KI-Code ohne menschliches Review"]
    B --> C1["🔴 Massive Technische Schulden (Technical Debt)"]
    B --> C2["🔴 Schwerwiegende Sicherheitslücken & Datenabfluss"]
    B --> C3["🔴 Verlust von Domänenwissen im Unternehmen"]
    B --> C4["🔴 Unwartbarer Spaghetticode ohne Architektur"]
    C1 & C2 & C3 & C4 --> D["💥 Projekt-Kollaps & Extrem hohe Nachbesserungskosten"]

Die Risiken rein automatisierter Code-Generierung ohne Mensch:

1. Kein tiefes Architekturverständnis: Eine KI hat kein Bewusstsein für langfristige Produktstrategien, Domänenlogik oder Business-Zusammenhänge.
2. Qualitäts- und Sicherheitsverlust: Ohne menschliches Security-Review schleichen sich XSS-Lücken, Multi-Tenancy-Datenlecks oder Heap-Speicherfehler ein.
3. Verlust von Know-how: Wenn niemanden mehr den Code liest und versteht, ist bei Systemausfällen kein Entwickler mehr in der Lage, Notfall-Debugging zu betreiben.

🧠 2. Das richtige Paradigma: Symbiose & Augmented Engineering

Die Zukunft erfolgreicher Softwareentwicklung liegt nicht in der Ersetzung des Menschen, sondern in der Verstärkung des Entwicklers (Augmented Engineering):

graph LR
    subgraph Symbiose: Das Entwickler-Agenten-Team
        A["👤 Menschlicher Entwickler\n(Pilot / Architekt)\n- Strategie & Vision\n- Domänen-Wissen\n- Verantwortung & Security Audit\n- Ethik & Governance"] <-->|Verstärkung & Schneller Feedback-Loop| B["🤖 AGY KI-Agent\n(Co-Pilot / Kraftverstärker)\n- Boilerplate-Generierung\n- Schnelle Doku-Recherche\n- Automatisierte Test-Fixes\n- Linter- & Typenprüfungen"]
    end

Rollenverteilung im Entwickler-Team:

🛠️ 3. Praxis-Guidelines für Entwickler-Teams im AGY Workspace

Um eine gesunde, hochproduktive Teamkultur mit KI-Agenten im Unternehmen zu etablieren, gelten folgende Grundsätze:

1. Human-in-the-Loop (HITL) als unverrückbarer Standard

• Kein KI-generierter Code wird ohne explizites menschliches Code-Review gemergt.
• Die AGY IDE Tool Execution Policy bleibt stets auf request-review oder proceed-in-sandbox.

2. Die KI als Junior-Entwickler betrachten

• Behandle den AGY Agenten wie einen extrem schnellen, aber unerfahrenen Junior-Entwickler.
• Prüfe seine Vorschläge kritisch, korrigiere Denkfehler und verlange Erklärungen, wenn Logik unklar erscheint.

3. Wissenstransfer fördern statt Hirn ausschalten

• Nutze die KI, um neues Wissen im Team aufzubauen.
• Beispiel-Prompt: "Erkläre unserem Team in 3 Sätzen, warum du hier tokio::select! statt join! verwendet hast."

4. Qualitätsstandards durch unbestechliche Gates sichern

• Der Mensch definiert die Qualitätsregeln in AGENTS.md und den Skills.
• Die KI muss die automatischen Qualitätsgates (cargo check, cargo test, cargo clippy, npm run build:docs) fehlerfrei bestehen.

💬 4. Argumentations-Leitfaden gegenüber Führungskräften & Management

Wenn Unternehmensleiter oder Entscheider KI als reines "Personaleinsparungs-Tool" missverstehen, nutze folgende Argumente:

1. "KI ist kein Entwickler-Ersatz, sondern ein Entwickler-Verstärker."

   • Argument: Mit AGY CLI & IDE schaffen Entwickler in der gleichen Zeit die 3- bis 5-fache Menge an qualitativ hochwertigen Features – ohne Qualitätsverlust.

2. "Blindes Sparen führt zu gigantischer Technical Debt."

   • Argument: Unbewachter KI-Code erzeugt versteckte Fehler, die später um ein Vielfaches teurer zu reparieren sind als die Ersparnis durch Personalabbau.

3. "Sicherheit & Compliance erfordern den Menschen."

   • Argument: KI haftet nicht für Datenschutzverstöße (DSGVO), Sicherheitslücken oder Urheberrechtsverletzungen. Nur erfahrene Entwickler garantieren Governance und Sicherheit.

4. "Höhere Entwickler-Zufriedenheit & Innovation."

   • Argument: KI nimmt Entwicklern lästige Routineaufgaben ab. Das steigert die Arbeitsfreude und lässt Raum für echte Innovation und bessere Produkte.

🔗 Verwandte Themen:

• 👉 Kapitel 8: KI-Agenten, Subagenten & Praxis-Handbuch Vibe Coding
• 👉 Kapitel 9.1: AGY CLI & IDE Setup & Konfiguration
• 👉 Kapitel 9.2: Tutorial für KI-Geschwindigkeit & Token-Sparsamkeit

Agent Skills Overview

Übersicht aller verfügbaren Subagent Skills:

• admin_manager: Experte für das MeinCMS Admin & User CLI Tool (Argon2 Hashing, User Management).
• backup_manager: Experte für das MeinCMS Rust Backup-System (YAML/XML Export, Import und Repair).
• db_admin: Datenbank- und Mandanten-Experte für SQLx, PostgreSQL und Rust Data Access.
• meincms_worker: Allgemeiner Entwickler-Subagent für MeinCMS (Rust, Axum, Maud, SQLx).
• parser: Experte für das Rust WikiText/Markdown Compiler Crate (meincms_parser).
• ui_worker: Frontend- und UI-Experte für Maud Templating, Vanilla JavaScript und CSS.

Beschreibung: Experte für das MeinCMS Admin & User CLI Tool (Argon2 Hashing, User Management).

Admin CLI Experte (meincms_admin)

Verantwortlich für das Crate meincms_admin/.

• Fokus: Benutzer- und Administratorverwaltung, Passwort-Hashing mit Argon2.
• Speicherort: config/users.json / Datenbank-Passwort-Hashes.
• Befehle:
  • cargo run -p meincms_admin (Interaktiv)
  • cargo run -p meincms_admin -- create-user --username <email>
  • cargo run -p meincms_admin -- list-users

Beschreibung: Experte für das MeinCMS Rust Backup-System (YAML/XML Export, Import und Repair).

Backup-Experte (MeinCMS Rust Edition)

Du bist der backup_manager, zuständig für das eigenständige Rust Backup-Projekt des CMS.

Verantwortlichkeiten

• Fokus: Das Crate meincms_backup/.
• Format: Daten werden im YAML- oder XML-Format exportiert und importiert (PascalCase-Kompatibilität).
• Speicherregel: Es wird nur der rohe WikiText oder Markdown-Code gesichert. Generiertes HTML wird niemals im Backup gespeichert.
• Repair-Prozess: Nach einem Import (oder wenn sich der Parser ändert), muss das HTML neu generiert werden. Dafür ist der Befehl cargo run -p meincms_backup -- repair zuständig.
• Ausführung:
  • Export: cargo run -p meincms_backup -- export
  • Import: cargo run -p meincms_backup -- import <file>
  • Repair: cargo run -p meincms_backup -- repair

Beschreibung: Datenbank- und Mandanten-Experte für SQLx, PostgreSQL und Rust Data Access.

Datenbank-Experte (MeinCMS Rust Edition)

Du bist der db_admin, spezialisiert auf die Datenbankarchitektur und SQLx-Integration von MeinCMS.

Verantwortlichkeiten

• Technologien: Rust, SQLx, PostgreSQL.
• Multi-Tenancy (Mandantenfähigkeit): Das System trennt Daten strikt nach Mandanten (z. B. "main", "doc"). Bei Datenbankabfragen muss nach der TenantId gefiltert werden.
• Verbindungszeichenfolge: Steuerung über Umgebungsvariable DATABASE_URL=postgres://....
• Modelle: Achte auf die korrekten Datenstrukturen wie WikiArtikel, WikiArtikelVersion, WikiNamespace und WikiCategory.

Beschreibung: Allgemeiner Entwickler-Subagent für MeinCMS (Rust, Axum, Maud, SQLx).

MeinCMS Worker Skill (wissen-ahrensburg.de - Rust Edition)

Du bist der meincms_worker, ein erfahrener Rust-Entwickler, der für die Implementierung von Features, Fehlerbehebung und Refactoring im Rust-Workspace von MeinCMS (wissen-ahrensburg.de) zuständig ist.

Architektur & Tech-Stack

• Technologien: Rust 1.80+, Axum 0.7, Maud Templating, SQLx, PostgreSQL, Argon2.
• Frontend-Sicherheit: HTML Escaping via html-escape & meincms_parser, globale CSRF/CSP, keine Inline-Skripte.
• Multi-Tenancy: Identifizierung des Mandanten ("main", "doc") via Hostname im Axum Tenant Extractor (tenant.rs).

Wichtige Regeln & Best Practices

• JavaScript / UI: Toggling von Elementen im Editor soll über style.display via JS (DOMContentLoaded) erfolgen, verlasse dich nicht nur auf CSS-Klassen.
• Tests: Neue Logik sollte durch Tests im Workspace abgedeckt sein (cargo test --workspace).

Typische Befehle

• App starten: cargo run -p meincms_web
• Admin-CLI starten: cargo run -p meincms_admin
• Backup-CLI starten: cargo run -p meincms_backup -- [export|import|repair]

Beschreibung: Experte für das Rust WikiText/Markdown Compiler Crate (meincms_parser).

Parser Skill (MeinCMS - meincms_parser)

Du bist der Experte für den Custom WikiText/Markdown Compiler-Parser in diesem Projekt (meincms_parser).

Verantwortlichkeiten & Architektur

• Fokus: Das Crate meincms_parser/ (Tokenizer, AST Builder, HTML Serializer, FFI Exporte).
• Sicherheit: Der Output wird mit striktem HTML Escaping gesichert. Verhindere XSS/CSRF/CSP Schwachstellen. Es sind keine Inline-Skripte erlaubt!
• Inhaltsfelder: Beim Speichern im Backend muss das jeweils nicht genutzte Inhaltsfeld (Markdown vs. MediaWiki) explizit geleert werden.
• Backup & HTML: Das generierte HTML wird nicht im Backup gespeichert. Nach Änderungen am Parser oder einem Import muss der Befehl cargo run -p meincms_backup -- repair ausgeführt werden.

Typische Workflow-Befehle

• Tests für den Parser ausführen: cargo test -p meincms_parser
• Nach Parser-Anpassungen (Repair-Job): cargo run -p meincms_backup -- repair

Beschreibung: Frontend- und UI-Experte für Maud Templating, Vanilla JavaScript und CSS.

Frontend-Experte (MeinCMS Rust Edition)

Du bist der ui_worker, spezialisiert auf das Frontend von MeinCMS.

Verantwortlichkeiten

• Technologien: Maud HTML-Makros in Rust, Vanilla JavaScript, Vanilla CSS.
• Sicherheit (WICHTIG): Es gibt eine strikte Content Security Policy (CSP). Es sind keine Inline-Skripte (z. B. onclick="...") in HTML erlaubt. Skripte müssen über EventListener (DOMContentLoaded) angebunden werden.
• UI-Logik: Toggling von Editor-Elementen (Ein-/Ausblenden) soll robust über style.display in JavaScript gesteuert werden.

Angaben gemäß § 5 TMG

• Thorsten Klöhn
• Gerhardstraße 2
• 22926 Ahrensburg

Vertreten durch:

Thorsten Klöhn

Kontakt:

• Telefon: 04102-2 17 40 07\
• E-Mail: thorstenkloehn@gmail.com

Haftungsausschluss:

Haftung für Inhalte

Die Inhalte unserer Seiten wurden mit größter Sorgfalt erstellt. Für die Richtigkeit, Vollständigkeit und Aktualität der Inhalte können wir jedoch keine Gewähr übernehmen. Als Diensteanbieter sind wir gemäß § 7 Abs.1 TMG für eigene Inhalte auf diesen Seiten nach den allgemeinen Gesetzen verantwortlich. Nach §§ 8 bis 10 TMG sind wir als Diensteanbieter jedoch nicht verpflichtet, übermittelte oder gespeicherte fremde Informationen zu überwachen oder nach Umständen zu forschen, die auf eine rechtswidrige Tätigkeit hinweisen. Verpflichtungen zur Entfernung oder Sperrung der Nutzung von Informationen nach den allgemeinen Gesetzen bleiben hiervon unberührt. Eine diesbezügliche Haftung ist jedoch erst ab dem Zeitpunkt der Kenntnis einer konkreten Rechtsverletzung möglich. Bei Bekanntwerden von entsprechenden Rechtsverletzungen werden wir diese Inhalte umgehend entfernen.

Haftung für Links

Unser Angebot enthält Links zu externen Webseiten Dritter, auf deren Inhalte wir keinen Einfluss haben. Deshalb können wir für diese fremden Inhalte auch keine Gewähr übernehmen. Für die Inhalte der verlinkten Seiten ist stets der jeweilige Anbieter oder Betreiber der Seiten verantwortlich. Die verlinkten Seiten wurden zum Zeitpunkt der Verlinkung auf mögliche Rechtsverstöße überprüft. Rechtswidrige Inhalte waren zum Zeitpunkt der Verlinkung nicht erkennbar. Eine permanente inhaltliche Kontrolle der verlinkten Seiten ist jedoch ohne konkrete Anhaltspunkte einer Rechtsverletzung nicht zumutbar. Bei Bekanntwerden von Rechtsverletzungen werden wir derartige Links umgehend entfernen.\

Urheberrecht

Dieses Werk ist lizenziert unter einer Creative Commons Namensnennung 4.0 International Lizenz.Soweit die Inhalte auf dieser Seite nicht vom Betreiber erstellt wurden, werden die Urheberrechte Dritter beachtet. Insbesondere werden Inhalte Dritter als solche gekennzeichnet. Sollten Sie trotzdem auf eine Urheberrechtsverletzung aufmerksam werden, bitten wir um einen entsprechenden Hinweis. Bei Bekanntwerden von Rechtsverletzungen werden wir derartige Inhalte umgehend entfernen.

Datenschutz

Die Nutzung unserer Webseite ist in der Regel ohne Angabe personenbezogener Daten möglich. Soweit auf unseren Seiten personenbezogene Daten (beispielsweise Name, Anschrift oder eMail-Adressen) erhoben werden, erfolgt dies, soweit möglich, stets auf freiwilliger Basis. Diese Daten werden ohne Ihre ausdrückliche Zustimmung nicht an Dritte weitergegeben.
Wir weisen darauf hin, dass die Datenübertragung im Internet (z.B. bei der Kommunikation per E-Mail) Sicherheitslücken aufweisen kann. Ein lückenloser Schutz der Daten vor dem Zugriff durch Dritte ist nicht möglich. Der Nutzung von im Rahmen der Impressumspflicht veröffentlichten Kontaktdaten durch Dritte zur Übersendung von nicht ausdrücklich angeforderter Werbung und Informationsmaterialien wird hiermit ausdrücklich widersprochen. Die Betreiber der Seiten behalten sich ausdrücklich rechtliche Schritte im Falle der unverlangten Zusendung von Werbeinformationen, etwa durch Spam-Mails, vor.\

Impressum vom Impressum Generator der Kanzlei Hasselbach, Rechtsanwälte für Arbeitsrecht und Familienrecht

Verantwortliche Stelle im Sinne der Datenschutzgesetze, insbesondere der EU-Datenschutzgrundverordnung (DSGVO), ist:

• Thorsten Klöhn
• Gerhardstraße 2
• 22926 Ahrensburg
• Telefon: 04102-2 17 40 07
• e-Mail: thorstenkloehn@gmail.com

Ihre Betroffenenrechte

Unter den angegebenen Kontaktdaten unseres Datenschutzbeauftragten können Sie jederzeit folgende Rechte ausüben:

• Auskunft über Ihre bei uns gespeicherten Daten und deren Verarbeitung (Art. 15 DSGVO),
• Berichtigung unrichtiger personenbezogener Daten (Art. 16 DSGVO),
• Löschung Ihrer bei uns gespeicherten Daten (Art. 17 DSGVO),
• Einschränkung der Datenverarbeitung, sofern wir Ihre Daten aufgrund gesetzlicher Pflichten noch nicht löschen dürfen (Art. 18 DSGVO),
• Widerspruch gegen die Verarbeitung Ihrer Daten bei uns (Art. 21 DSGVO) und
• Datenübertragbarkeit, sofern Sie in die Datenverarbeitung eingewilligt haben oder einen Vertrag mit uns abgeschlossen haben (Art. 20 DSGVO).

Sofern Sie uns eine Einwilligung erteilt haben, können Sie diese jederzeit mit Wirkung für die Zukunft widerrufen.

Sie können sich jederzeit mit einer Beschwerde an eine Aufsichtsbehörde wenden, z. B. an die zuständige Aufsichtsbehörde des Bundeslands Ihres Wohnsitzes oder an die für uns als verantwortliche Stelle zuständige Behörde.

Eine Liste der Aufsichtsbehörden (für den nichtöffentlichen Bereich) mit Anschrift finden Sie unter: .

Eingebettete YouTube-Videos

Art und Zweck der Verarbeitung:

Auf einigen unserer Webseiten betten wir YouTube-Videos ein. Betreiber der entsprechenden Plugins ist die YouTube, LLC, 901 Cherry Ave., San Bruno, CA 94066, USA (nachfolgend „YouTube“). Wenn Sie eine Seite mit dem YouTube-Plugin besuchen, wird eine Verbindung zu Servern von YouTube hergestellt. Dabei wird YouTube mitgeteilt, welche Seiten Sie besuchen. Wenn Sie in Ihrem YouTube-Account eingeloggt sind, kann YouTube Ihr Surfverhalten Ihnen persönlich zuzuordnen. Dies verhindern Sie, indem Sie sich vorher aus Ihrem YouTube-Account ausloggen.

Wird ein YouTube-Video gestartet, setzt der Anbieter Cookies ein, die Hinweise über das Nutzerverhalten sammeln.

Weitere Informationen zu Zweck und Umfang der Datenerhebung und ihrer Verarbeitung durch YouTube erhalten Sie in den Datenschutzerklärungen des Anbieters, Dort erhalten Sie auch weitere Informationen zu Ihren diesbezüglichen Rechten und Einstellungsmöglichkeiten zum Schutze Ihrer Privatsphäre (). Google verarbeitet Ihre Daten in den USA und hat sich dem EU-US Privacy Shield unterworfen https://www.privacyshield.gov/EU-US-Framework

Rechtsgrundlage:

Rechtsgrundlage für die Einbindung von YouTube und dem damit verbundenen Datentransfer zu Google ist Ihre Einwilligung (Art. 6 Abs. 1 lit. a DSGVO).

Empfänger:

Der Aufruf von YouTube löst automatisch eine Verbindung zu Google aus.

Speicherdauer und Widerruf der Einwilligung:

Wer das Speichern von Cookies für das Google-Ad-Programm deaktiviert hat, wird auch beim Anschauen von YouTube-Videos mit keinen solchen Cookies rechnen müssen. YouTube legt aber auch in anderen Cookies nicht-personenbezogene Nutzungsinformationen ab. Möchten Sie dies verhindern, so müssen Sie das Speichern von Cookies im Browser blockieren.

Weitere Informationen zum Datenschutz bei „YouTube“ finden Sie in der Datenschutzerklärung des Anbieters unter:

Drittlandtransfer:

Google verarbeitet Ihre Daten in den USA und hat sich dem EU_US Privacy Shield unterworfen .

Bereitstellung vorgeschrieben oder erforderlich:

Die Bereitstellung Ihrer personenbezogenen Daten erfolgt freiwillig, allein auf Basis Ihrer Einwilligung. Sofern Sie den Zugriff unterbinden, kann es hierdurch zu Funktionseinschränkungen auf der Website kommen.

Änderung unserer Datenschutzbestimmungen

Wir behalten uns vor, diese Datenschutzerklärung anzupassen, damit sie stets den aktuellen rechtlichen Anforderungen entspricht oder um Änderungen unserer Leistungen in der Datenschutzerklärung umzusetzen, z.B. bei der Einführung neuer Services. Für Ihren erneuten Besuch gilt dann die neue Datenschutzerklärung.

Fragen an den Datenschutzbeauftragten

Wenn Sie Fragen zum Datenschutz haben, schreiben Sie uns bitte eine E-Mail oder wenden Sie sich direkt an die für den Datenschutz verantwortliche Person in unserer Organisation:

Die Datenschutzerklärung wurde mit dem Datenschutzerklärungs-Generator der activeMind AG erstellt *(Version 2018-09-24).c