tom/hugin
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
hugin/README.md

8.6 KiB
Raw Permalink Blame History

Hugin

Register für Skills, Regeln, Befehle, Subagenten und MCP-Anbindungen für Claude Code und OpenCode. Konzept: 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.

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:

(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

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):

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 (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

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

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.

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.

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 -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.