165 lines
8.6 KiB
Markdown
165 lines
8.6 KiB
Markdown
# 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 „Prüfer“: unter „Prüfungen“ wartet
|
|
`pub-munin-nutzen 1.5.0`. Als „Autor“ 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=<Key „Shop CI“ aus .demo/keys.txt>
|
|
<hugin>/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
|
|
<hugin>/cli/dist/hugin sync
|
|
```
|
|
|
|
MCP in Claude Code oder OpenCode: Server `http://127.0.0.1:8080/mcp` mit Kopfzeile
|
|
`Authorization: Bearer <Projekt-Key>`.
|
|
|
|
## 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=<anbieter/modell> 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 <hugin>/contract/examples/bundles/first-install
|
|
hugin check --bundle <hugin>/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=<pfad zu 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 <ordner>` | 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 <version> [download-ordner]` | CLI für macOS, Linux, Windows bauen, mit SHA256SUMS |
|
|
| `uv run hugin-server export <ordner> [--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://<rechner>:8080 -Key <Key „Softwareverteilung“ aus .demo/keys.txt>
|
|
```
|
|
|
|
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.
|