# Hugin Register für Skills, Regeln, Befehle, Subagenten und MCP-Anbindungen für Claude Code und OpenCode. Konzept: [KONZEPT.md](KONZEPT.md). | Ordner | Inhalt | |---|---| | `contract/` | Bundle-Format (JSON-Schema), Beispielpakete, goldene Bundles | | `server/` | Python: `hugin_core` (Quellformat, Linter, Übersetzer, Auflösung, Bundles) und `hugin_app` (FastAPI, Datenbank, API, Weboberfläche) | | `cli/` | Go: Programm `hugin` — Teams: `init`, `sync`, `check`, `status`, `search`, `login`; Autoren: `new`, `validate`, `try`, `upload`, `import` | | `scripts/` | siehe „Skripte“ unten | | `static/css-framework/` | CSS-Framework für die Weboberfläche | | `BETRIEB.md` | Container-Image, SQLite oder PostgreSQL, Sicherung | | `TESTEN.md` | Schritt für Schritt lokal testen: Demo, Test-Repo, Autorenablauf, alle Testskripte | | `STUFE0.md` | Ergebnisse der Verhaltensprüfungen von Claude Code und OpenCode | | `COMPATIBILITY.md` | Ergebnis des letzten Rauchtests mit den echten Werkzeugen (`scripts/tool-smoke-test.sh`) | ## Starten und ausprobieren Voraussetzungen: `uv`, Go ≥ 1.26, `zip`, `curl`. Für die Browser-Prüfungen Google Chrome. ```sh scripts/demo.sh # Server mit Beispieldaten auf http://127.0.0.1:8080; Keys stehen in .demo/keys.txt ``` In der Weboberfläche mit einem der Keys anmelden, z. B. als Bert (Prüfer): unter „Prüfungen“ wartet `pub-munin-nutzen 1.5.0`. Als Anna (Autorin) hochladen, als Shop-Admin Personen und Keys anlegen, als Plattform-Admin (`demo-admin`) die Systemseite. Mit dem CLI ein Repo abgleichen: ```sh (cd cli && go build -o dist/hugin ./cmd/hugin) cd /path/to/test-repo export HUGIN_KEY= /cli/dist/hugin init --server http://127.0.0.1:8080 --project api # in .hugin.yaml unter packages: z. B. - pub-munin-nutzen und - pub-release-notiz /cli/dist/hugin sync ``` MCP in Claude Code oder OpenCode: Server `http://127.0.0.1:8080/mcp` mit Kopfzeile `Authorization: Bearer `. ## Testen ```sh cd server && uv run pytest # Server: Kern, API, Web, MCP, Stufe 4, Isolation der Tenants (SQLite) scripts/postgres-test.sh # dieselbe Suite gegen PostgreSQL in Docker cd server && uv run pytest --update # goldene Bundles neu schreiben (nach gewollter Änderung) cd cli && go test ./... # CLI, wendet die goldenen Bundles an ``` Erst die Server-Tests, dann die CLI-Tests: Die CLI testet gegen die Bundles, die der Server erzeugt. Vor einem Release und nach größeren Updates von Claude Code oder OpenCode zusätzlich mit den echten Werkzeugen (kostet Tokens, braucht für beide einen Modellzugang): ```sh scripts/stage0.sh # Verhalten von OpenCode, ohne Modellaufruf OPENCODE_MODEL= scripts/tool-smoke-test.sh # schreibt COMPATIBILITY.md ``` ## Stand Umgesetzt sind die Stufen 0 bis 4 aus [KONZEPT.md](KONZEPT.md) (Abschnitt 20). Offen: - Stufe 5: lokale MCP-Server mit Python und OpenCode-Plugins (ohne npm-Abhängigkeiten) sind umgesetzt (Windows von Hand ungeprüft, `TESTEN.md` 5.11); offen sind fertige Programme als lokale Server, npm-Abhängigkeiten für Plugins, Hooks (Claude Code), Paare, Signaturen - OpenCode 2 ist ungeprüft (STUFE0.md, Frage 10) - Untergrenzen der Werkzeuge sind vorläufig: geprüft sind nur aktuelle Versionen - `hugin-install.ps1` ist mit PowerShell 7 getestet, unter Windows PowerShell 5.1 noch nicht ## CLI bauen und ohne Server ausprobieren ```sh cd cli && go build -o dist/hugin ./cmd/hugin cd /path/zum/test-repo hugin init --server https://hugin.intern --project shop hugin sync --bundle /contract/examples/bundles/first-install hugin check --bundle /contract/examples/bundles/first-install ``` ## Server lokal starten ```sh cd server export HUGIN_DATABASE_URL=sqlite:///hugin.db HUGIN_ADMIN_TOKEN=geheim uv run hugin-server migrate uv run hugin-server run --port 8080 # API-Doku unter http://localhost:8080/docs ``` Erste Schritte mit dem Admin-Token: Tenant anlegen (`POST /api/v1/admin/tenants`), Projekt (`…/tenants/{slug}/projects`), Keys (`…/tenants/{slug}/keys`). `scripts/smoke-test-local.sh` macht genau das und gleicht danach ein Test-Repo ab. | Umgebungsvariable | Bedeutung | |---|---| | `HUGIN_DATABASE_URL` | z. B. `sqlite:///hugin.db` oder `postgresql+psycopg://…` | | `HUGIN_ADMIN_TOKEN` | Plattform-Admin | | `HUGIN_BASE_URL` | steht im Kopf verwalteter Dateien | | `HUGIN_DOWNLOAD_DIR` | Ordner mit gebauten CLI-Programmen (`scripts/build-cli.sh`), für die Seite „Programm hugin“ | | `HUGIN_CLI_MIN_VERSION` | ältere CLIs meldet `hugin check` als Befund (Standard 0.1.0) | | `HUGIN_RATE_LIMIT` | Anfragen je Key und Minute (Standard 600) | | `HUGIN_FAILED_ATTEMPTS` | falsche Keys je IP in 5 Minuten, danach 429 (Standard 20) | | `HUGIN_PROXY_IPS` | Router/Ingress, deren `X-Forwarded-For` gilt (Standard `127.0.0.1`; OpenShift: Router-Netz, z. B. `10.128.0.0/14`) | | `HUGIN_MAX_UPLOAD_MB` | größter Request-Body, vor der Anmeldung geprüft (Standard 40) | Die Weboberfläche liegt unter `/` (Anmeldung mit einem Key), die Online-Hilfe unter `/help` (ohne Anmeldung), die API-Doku unter `/api/docs`. Mit PostgreSQL statt SQLite: `docker compose up -d`, dann `HUGIN_DATABASE_URL=postgresql+psycopg://hugin:hugin@127.0.0.1:55432/hugin scripts/demo.sh`. ## Container-Image `server/Dockerfile` baut auf Red Hat UBI 9 minimal mit Python 3.12 (ca. 90 MB), die Abhängigkeiten kommen fest aus `uv.lock`. Das Image läuft als beliebiger Benutzer der Gruppe 0 (OpenShift) und auch mit schreibgeschütztem Dateisystem. ```sh docker build -t hugin server/ docker run --rm -e HUGIN_DATABASE_URL=… hugin migrate # Migrations-Job vor dem Rollout docker run -p 8080:8080 -e HUGIN_DATABASE_URL=… -e HUGIN_ADMIN_TOKEN=… hugin # Server (CMD run) ``` Probes: `/healthz` (lebt), `/readyz` (Datenbank erreichbar, Migrationen aktuell), Port 8080. Ohne `HUGIN_DATABASE_URL` nutzt das Image SQLite unter `/data/hugin.db`: dort ein Volume einhängen, nur ein Pod, Strategie `Recreate`. Mit PostgreSQL braucht es kein Volume. Ausführlich (SQLite oder PostgreSQL, Sicherung, Probes): [BETRIEB.md](BETRIEB.md). ## Skripte | Skript | Zweck | |---|---| | `scripts/demo.sh` | Server mit Beispieldaten und Keys für alle Rollen | | `scripts/integration-test.sh` | Auslieferung an Integrationen mit `hugin-install.ps1` (`PWSH=`) | | `scripts/integration-test.ps1` | dasselbe unter Windows PowerShell 5.1, gegen einen laufenden Hugin (siehe unten) | | `scripts/postgres-test.sh [--compose]` | ganze Server-Testsuite gegen PostgreSQL 17.6 in Docker (Wegwerf-Container oder die aus `docker-compose.yml`) | | `docker compose up -d` | dauerhafte PostgreSQL auf 127.0.0.1:55432 (Daten im Volume; `docker compose down -v` löscht sie) | | `scripts/smoke-test-local.sh` | Server starten, Pakete veröffentlichen, mit dem CLI abgleichen; dazu der Ablauf für Autoren (`new`, `validate`, `try`, `upload`) | | `scripts/stage0.sh` | Verhalten von OpenCode prüfen, ohne Modellaufruf (→ STUFE0.md) | | `scripts/tool-smoke-test.sh` | Rauchtest mit echtem Claude Code und OpenCode, schreibt `COMPATIBILITY.md`; kostet Tokens (`TOOLS`, `CLAUDE_MODEL`, `OPENCODE_MODEL`, `KEEP=1`) | | `scripts/csp-test.sh` | CSS-Framework unter strenger CSP: Verstöße zählen, alle `data-action` durchklicken (Chrome) | | `uv run --no-project --with websockets --with httpx python scripts/csp/web_browser.py ` | Weboberfläche in Chrome: CSP-Verstöße je Seite, Bildschirmfotos hell und dunkel | | `uv run --no-project --with websockets --with httpx python scripts/csp/web_actions.py` | Weboberfläche in Chrome bedienen: Live-Suche, Tabs, Kopieren, Rückfragen, Felder je Key-Art, Prüfungs-Dialog, Editor | | `scripts/build-cli.sh [download-ordner]` | CLI für macOS, Linux, Windows bauen, mit SHA256SUMS | | `uv run hugin-server export [--commit]` | freigegebene Pakete im Quellformat exportieren (in `server/`) | | `scripts/sync-framework.sh` | gebautes CSS-Framework nach `server/src/hugin_app/static/` kopieren | ## Integration unter Windows PowerShell 5.1 testen 1. Auf dem Mac oder Linux-Rechner: `HOST=0.0.0.0 scripts/demo.sh` 2. `scripts/integration-test.ps1` auf den Windows-Rechner kopieren. 3. Dort in Windows PowerShell 5.1 (nicht `pwsh`): ```powershell powershell -ExecutionPolicy Bypass -File integration-test.ps1 ` -Server http://:8080 -Key ``` Das Skript lädt `hugin-install.ps1` vom Server, installiert in einen Temp-Ordner, prüft Encoding, Zeilenenden, JSON, zweiten Lauf, Abbestellen, Handänderung und JSONC und meldet je Prüfung OK oder FEHLER. Es ändert nichts außerhalb des Temp-Ordners.