chore: Repo-Struktur vollständig aufsetzen

- Workflows: docker-publish.yml → nightly.yml + release.yml + pr-check.yml (nightly: Branch-Push + Cron 02:00, release: v*-Tag, pr-check: lint+tests) - Issue-Templates: bug_report.md + feature_request.md (englisch) - PR-Template: pull_request_template.md (englisch) - Claude-Agenten: reviewer, changelog, test-writer, nightly-prep, docker-check, moonraker-debug + settings.json - agents.md: Agenten-Übersicht im Repo-Root - .gitignore: .runner-token + secrets/ ausgeschlossen
2026-06-24 13:21:29 +02:00
parent c9043e9630
commit 877cddb1ba
16 changed files with 416 additions and 59 deletions
--- a/.claude/agents/changelog.md
+++ b/.claude/agents/changelog.md
@@ -0,0 +1,31 @@
+---
+name: KX-Bridge Changelog
+description: Generiert einen CHANGELOG.md Eintrag aus Git-Commits seit dem letzten Tag.
+tools:
+  - run_command
+  - read_file
+  - write_file
+---
+
+Du generierst CHANGELOG.md Einträge für KX-Bridge.
+
+Vorgehen:
+1. Führe aus: `git log $(git describe --tags --abbrev=0)..HEAD --oneline`
+2. Gruppiere Commits nach Präfix: feat → Neu, fix → Behoben, chore/refactor/docs → Geändert
+3. Frage nach der Versionsnummer (SemVer: feat→MINOR, fix→PATCH, breaking→MAJOR)
+4. Schreibe den Abschnitt im Format:
+
+```
+## [VERSION] - DATUM
+
+### Neu
+- ...
+
+### Behoben
+- ...
+
+### Geändert
+- ...
+```
+
+5. Füge den Abschnitt am Anfang der bestehenden CHANGELOG.md ein, ohne vorhandene Einträge zu ändern.
--- a/.claude/agents/docker-check.md
+++ b/.claude/agents/docker-check.md
@@ -0,0 +1,32 @@
+---
+name: KX-Bridge Docker Check
+description: Prüft Dockerfile, docker-compose und das gebaute Image auf häufige Probleme.
+tools:
+  - read_file
+  - run_command
+  - search_files
+---
+
+Du prüfst die Docker-Konfiguration von KX-Bridge.
+
+**Dockerfile:**
+- Base-Image aktuell? (`python:3.11-slim` oder neuer)
+- `.dockerignore` vorhanden und vollständig?
+- Keine Secrets oder Zertifikate im Image (`anycubic_slicer.crt/.key` darf NICHT eingebettet sein)
+- Healthcheck vorhanden?
+- Kein `COPY . .` ohne `.dockerignore`
+
+**docker-compose.yml:**
+- Port 7125 korrekt gemappt
+- Config-Volume gemountet (`/app/config`)
+- `restart: unless-stopped` gesetzt
+- Logging-Limits konfiguriert (`max-size`, `max-file`)
+
+**Image-Check (falls lokal vorhanden):**
+```bash
+docker image inspect gitea.it-drui.de/viewit/kx-bridge:nightly
+```
+- Image-Größe sinnvoll (< 500MB)?
+- Keine privaten Keys eingebettet: `docker history --no-trunc`
+
+Berichte nach Schweregrad: Kritisch / Warnung / Hinweis.
--- a/.claude/agents/moonraker-debug.md
+++ b/.claude/agents/moonraker-debug.md
@@ -0,0 +1,23 @@
+---
+name: KX-Bridge Moonraker Debug
+description: Analysiert Moonraker/Klipper Logs und KX-Bridge Ausgaben auf Fehlerursachen.
+tools:
+  - read_file
+  - search_files
+---
+
+Du analysierst Logs für KX-Bridge im Kontext Moonraker/Klipper/AFC.
+
+**Bekannte Problemquellen:**
+- AFC lane_data Indizierung: korrekt ist `lane1`–`lane4` (flat), nicht Slot 0–3
+- `filament_id` muss als String übertragen werden, nicht als Integer
+- Moonraker WebSocket trennt bei Inaktivität → keep-alive prüfen
+- OrcaSlicer sendet Bambu MQTT Format → KX-Bridge muss übersetzen
+- ACE 2 Pro meldet Fehler wenn Lane leer aber als belegt markiert ist
+- MQTT mTLS: Zertifikat muss neben dem Binary liegen (`anycubic_slicer.crt/.key`)
+
+**Bei einem Log:**
+1. Identifiziere den **ersten** Fehler (nicht den letzten Symptom)
+2. Zeige den relevanten Log-Kontext (±10 Zeilen um den Fehler)
+3. Nenne die wahrscheinliche Ursache
+4. Schlage einen konkreten Fix vor (Datei + Funktion wenn möglich)
--- a/.claude/agents/nightly-prep.md
+++ b/.claude/agents/nightly-prep.md
@@ -0,0 +1,25 @@
+---
+name: KX-Bridge Nightly Prep
+description: Bereitet den PR von nightly nach main vor. Prüft ob alle Voraussetzungen für ein Stable Release erfüllt sind.
+tools:
+  - run_command
+  - read_file
+---
+
+Du bereitest einen nightly → main Merge für KX-Bridge vor.
+
+Führe folgende Checks aus und berichte:
+
+1. `git log main..nightly --oneline` → alle Commits die noch nicht in main sind
+2. `git diff main..nightly -- CHANGELOG.md` → ist CHANGELOG.md für alle Änderungen aktualisiert?
+3. Prüfe ob `tests/` alle geänderten Module abdeckt
+4. Prüfe ob Dockerfile ein aktuelles Base-Image verwendet
+5. Schlage eine SemVer-Versionsnummer vor:
+   - `feat:` Commits → MINOR erhöhen
+   - `fix:` Commits → PATCH erhöhen
+   - Breaking Change im Commit-Body → MAJOR erhöhen
+
+Abschlussbericht:
+- ✅ Bereit für Release
+- ⚠️ Offen: [Liste]
+- ❌ Blockiert durch: [Grund]
--- a/.claude/agents/reviewer.md
+++ b/.claude/agents/reviewer.md
@@ -0,0 +1,24 @@
+---
+name: KX-Bridge Reviewer
+description: Reviewt geänderte Dateien vor einem PR auf nightly. Prüft Logik, Fehlerbehandlung, Moonraker-Kompatibilität und Stil.
+tools:
+  - read_file
+  - list_directory
+  - search_files
+---
+
+Du bist Code-Reviewer für KX-Bridge — eine Python-Bridge zwischen OrcaSlicer und Moonraker/Klipper für den Anycubic Kobra X.
+
+Beim Review prüfst du:
+- Korrekte Fehlerbehandlung bei Moonraker HTTP/MQTT Calls (keine unbehandelten Exceptions)
+- Keine hardcodierten IPs oder Ports (müssen aus config.ini kommen)
+- Thread-Sicherheit bei parallelen Moonraker-Abfragen (asyncio korrekt verwendet)
+- AFC lane_data Struktur: flache Indizierung lane1–lane4, kein Slot-Mapping 0–3
+- Kein `print()` statt `logging` (außer in CLI-Hilfsfunktionen)
+- Typ-Annotationen vorhanden, Python 3.8+ kompatibel (kein `X | Y` Syntax)
+- Tests für neue öffentliche Funktionen vorhanden
+
+Ausgabeformat:
+1. **Kritische Fehler** — blockieren den Merge
+2. **Warnungen** — sollten vor Merge behoben werden
+3. **Hinweise** — optional, für zukünftige Verbesserungen
--- a/.claude/agents/test-writer.md
+++ b/.claude/agents/test-writer.md
@@ -0,0 +1,26 @@
+---
+name: KX-Bridge Test Writer
+description: Leitet pytest-Tests aus geänderten oder neuen Python-Dateien ab.
+tools:
+  - read_file
+  - write_file
+  - list_directory
+  - search_files
+---
+
+Du schreibst pytest-Tests für KX-Bridge.
+
+Kontext:
+- Moonraker API läuft auf Port 7125 (HTTP + WebSocket)
+- AFC lane_data: flache Indizierung lane1–lane4
+- Externe HTTP-Calls zu Moonraker werden mit `unittest.mock` gemockt
+- Python 3.8+ Kompatibilität (kein `X | Y` Union-Syntax)
+
+Für jede zu testende Funktion schreibst du:
+1. Happy Path (Normalfall mit validen Eingaben)
+2. Fehlerfall (Moonraker nicht erreichbar, Timeout, falsche Antwort)
+3. Grenzwerte (leere lane_data, ungültige filament_id, None-Werte)
+
+Dateiname: `tests/test_<modulname>.py`
+Verwende pytest-Fixtures für Moonraker-Mock-Responses.
+Keine echten Netzwerkaufrufe in Tests.
--- a/.claude/settings.json
+++ b/.claude/settings.json
@@ -0,0 +1,12 @@
+{
+  "project": "KX-Bridge",
+  "language": "de",
+  "defaultAgent": "reviewer",
+  "context": {
+    "repoBase": "gitea.it-drui.de/viewit/KX-Bridge-Release",
+    "defaultBranch": "nightly",
+    "stableBranch": "main",
+    "registry": "gitea.it-drui.de/viewit/kx-bridge",
+    "moonrakerPort": 7125
+  }
+}
--- a/.gitea/ISSUE_TEMPLATE/bug_report.md
+++ b/.gitea/ISSUE_TEMPLATE/bug_report.md
@@ -0,0 +1,29 @@
+---
+name: Bug Report
+about: Report a bug in KX-Bridge
+labels: bug
+---
+
+## Description
+<!-- What is happening? -->
+
+## Steps to Reproduce
+1.
+2.
+3.
+
+## Expected Behavior
+
+## Actual Behavior
+
+## Environment
+- KX-Bridge Version:
+- OrcaSlicer Version:
+- Moonraker/Klipper Version:
+- Operating System:
+- Installation: Docker / Binary
+
+## Logs
+```
+<!-- docker logs kx-bridge --tail 50 -->
+```
--- a/.gitea/ISSUE_TEMPLATE/feature_request.md
+++ b/.gitea/ISSUE_TEMPLATE/feature_request.md
@@ -0,0 +1,14 @@
+---
+name: Feature Request
+about: Suggest a new feature or improvement
+labels: enhancement
+---
+
+## Description
+<!-- What should be added or improved? -->
+
+## Motivation
+<!-- Why is this useful? What problem does it solve? -->
+
+## Proposed Implementation
+<!-- Optional: How could this be implemented technically? -->
--- a/.gitea/pull_request_template.md
+++ b/.gitea/pull_request_template.md
@@ -0,0 +1,21 @@
+## Description
+<!-- What does this PR change? -->
+
+## Related Issue
+Closes #
+
+## Type
+- [ ] Bug fix
+- [ ] Feature
+- [ ] Documentation
+- [ ] Refactoring
+
+## Tested with
+- OrcaSlicer Version:
+- Printer:
+- Moonraker/Klipper Version:
+
+## Checklist
+- [ ] Tests added/updated
+- [ ] CHANGELOG.md updated
+- [ ] No debug code included
--- a/.gitea/workflows/docker-publish.yml
+++ b/.gitea/workflows/docker-publish.yml
@@ -1,59 +0,0 @@
-name: Docker Publish
-
-on:
-  push:
-    tags:
-      - 'v*'
-    branches:
-      - nightly
-  workflow_dispatch:
-
-jobs:
-  build-push:
-    runs-on: self-hosted
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          clean: true
-
-      - name: Set up QEMU
-        uses: docker/setup-qemu-action@v3
-
-      - name: Set up buildx
-        uses: docker/setup-buildx-action@v3
-
-      - name: Login to Gitea registry
-        uses: docker/login-action@v3
-        with:
-          registry: gitea.it-drui.de
-          username: ${{ secrets.REGISTRY_USER }}
-          password: ${{ secrets.REGISTRY_TOKEN }}
-
-      - name: Derive tags
-        id: meta
-        run: |
-          REF="${GITHUB_REF}"
-          if [[ "$REF" == refs/tags/v* ]]; then
-            # Stable Release: :latest + :<VERSION>
-            VER=$(cat VERSION)
-            TAGS="gitea.it-drui.de/viewit/kx-bridge:latest"
-            TAGS="$TAGS,gitea.it-drui.de/viewit/kx-bridge:$VER"
-          else
-            # Nightly-Branch-Push: :nightly + :nightly-<DATUM>
-            DATE=$(date +%Y%m%d)
-            TAGS="gitea.it-drui.de/viewit/kx-bridge:nightly"
-            TAGS="$TAGS,gitea.it-drui.de/viewit/kx-bridge:nightly-$DATE"
-          fi
-          echo "tags=$TAGS" >>"$GITHUB_OUTPUT"
-          echo "Pushing tags: $TAGS"
-
-      - name: Build & push (amd64 + arm64)
-        uses: docker/build-push-action@v5
-        with:
-          context: .
-          platforms: linux/amd64,linux/arm64
-          push: true
-          provenance: false
-          no-cache: true
-          tags: ${{ steps.meta.outputs.tags }}
--- a/.gitea/workflows/nightly.yml
+++ b/.gitea/workflows/nightly.yml
@@ -0,0 +1,55 @@
+name: Nightly Build
+
+on:
+  push:
+    branches:
+      - nightly
+  schedule:
+    - cron: '0 2 * * *'
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: self-hosted
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          clean: true
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - name: Set up buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Login to Gitea registry
+        uses: docker/login-action@v3
+        with:
+          registry: gitea.it-drui.de
+          username: ${{ secrets.REGISTRY_USER }}
+          password: ${{ secrets.REGISTRY_TOKEN }}
+
+      - name: Build & push (amd64 + arm64)
+        run: |
+          DATE=$(date +%Y%m%d)
+          TAGS="gitea.it-drui.de/viewit/kx-bridge:nightly"
+          TAGS="$TAGS,gitea.it-drui.de/viewit/kx-bridge:nightly-$DATE"
+          docker buildx build \
+            --platform linux/amd64,linux/arm64 \
+            --push \
+            --provenance=false \
+            --no-cache \
+            $(echo "$TAGS" | tr ',' '\n' | sed 's/^/-t /') \
+            .
+
+      - name: Set nightly tag
+        env:
+          GITEA_TOKEN: ${{ secrets.RELEASE_TOKEN }}
+        run: |
+          DATE=$(date +%Y%m%d)
+          TAG="nightly-$DATE"
+          git config user.name "gitea-actions"
+          git config user.email "actions@it-drui.de"
+          git tag -f "$TAG"
+          git push origin "$TAG" --force
--- a/.gitea/workflows/pr-check.yml
+++ b/.gitea/workflows/pr-check.yml
@@ -0,0 +1,31 @@
+name: PR Check
+
+on:
+  pull_request:
+    branches:
+      - nightly
+
+jobs:
+  lint-and-test:
+    runs-on: self-hosted
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Python Setup
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Dependencies installieren
+        run: pip install -r requirements.txt
+
+      - name: Lint
+        run: |
+          pip install flake8
+          flake8 *.py --max-line-length=120 --extend-ignore=E501
+
+      - name: Tests
+        run: |
+          pip install pytest
+          pytest tests/ -v
+        if: ${{ hashFiles('tests/') != '' }}
--- a/.gitea/workflows/release.yml
+++ b/.gitea/workflows/release.yml
@@ -0,0 +1,58 @@
+name: Stable Release
+
+on:
+  push:
+    tags:
+      - 'v[0-9]+.[0-9]+.[0-9]+'
+
+jobs:
+  release:
+    runs-on: self-hosted
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          clean: true
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - name: Set up buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Login to Gitea registry
+        uses: docker/login-action@v3
+        with:
+          registry: gitea.it-drui.de
+          username: ${{ secrets.REGISTRY_USER }}
+          password: ${{ secrets.REGISTRY_TOKEN }}
+
+      - name: Build & push (amd64 + arm64)
+        run: |
+          VERSION="${GITHUB_REF#refs/tags/}"
+          docker buildx build \
+            --platform linux/amd64,linux/arm64 \
+            --push \
+            --provenance=false \
+            --no-cache \
+            -t "gitea.it-drui.de/viewit/kx-bridge:latest" \
+            -t "gitea.it-drui.de/viewit/kx-bridge:${VERSION}" \
+            .
+
+      - name: Create Gitea Release
+        env:
+          GITEA_TOKEN: ${{ secrets.RELEASE_TOKEN }}
+        run: |
+          VERSION="${GITHUB_REF#refs/tags/}"
+          CHANGELOG=$(awk "/^## \[${VERSION}\]/{found=1; next} found && /^## \[/{exit} found{print}" CHANGELOG.md || echo "")
+          curl -s -X POST \
+            -H "Authorization: token ${GITEA_TOKEN}" \
+            -H "Content-Type: application/json" \
+            "https://gitea.it-drui.de/api/v1/repos/viewit/KX-Bridge-Release/releases" \
+            -d "{
+              \"tag_name\": \"${VERSION}\",
+              \"name\": \"KX-Bridge ${VERSION}\",
+              \"body\": $(echo "$CHANGELOG" | python3 -c 'import sys,json; print(json.dumps(sys.stdin.read()))'),
+              \"draft\": false,
+              \"prerelease\": false
+            }"
--- a/.gitignore
+++ b/.gitignore
@@ -17,4 +17,8 @@ config/*.ini
 data/

 !data/orca_filaments.json
+
+# Sensitive files — never commit
 .runner-token
+secrets/
+*.token
--- a/agents.md
+++ b/agents.md
@@ -0,0 +1,31 @@
+# KX-Bridge Claude Agents
+
+## Available Agents
+
+| Agent | File | When to use |
+|---|---|---|
+| Reviewer | `.claude/agents/reviewer.md` | Before every PR — checks logic, error handling, Moonraker compatibility |
+| Changelog | `.claude/agents/changelog.md` | After merge to nightly — generates CHANGELOG.md entry from commits |
+| Test Writer | `.claude/agents/test-writer.md` | When adding new functions — derives pytest tests |
+| Nightly Prep | `.claude/agents/nightly-prep.md` | Before a release — checks readiness of nightly → main merge |
+| Docker Check | `.claude/agents/docker-check.md` | Before image push — validates Dockerfile and compose config |
+| Moonraker Debug | `.claude/agents/moonraker-debug.md` | On runtime errors — analyzes Moonraker/Klipper logs |
+
+## Usage
+
+In VS Code with Claude Code extension:
+```
+@reviewer     → code review of current changes
+@changelog    → generate CHANGELOG entry
+@test-writer  → write tests for changed files
+@nightly-prep → check release readiness
+@docker-check → validate Docker config
+@moonraker-debug → analyze logs
+```
+
+## Context
+
+- Moonraker API: Port 7125
+- AFC lane_data: flat indexing lane1–lane4
+- Registry: `gitea.it-drui.de/viewit/kx-bridge`
+- Default PR target: `nightly`