cubi-desktop
Quelle: pkr-lab/pkr-lab-docs/cubi/desktop.md
cubi-desktop
Desktop-Oberfläche für cubi. Sie enthält alle Bereiche des Terminal-cubi und zusätzlich die Pre-Push-Checks: Die CI-Checks eines Repos laufen lokal, bei grünem Ergebnis gibt es Push oder PR per Button. Die App liegt im cubi-Repo unter cubi-desktop/. Sie ist in Rust geschrieben, die Oberfläche nutzt egui/eframe.
Bereiche
| Bereich | Inhalt | Entspricht im Terminal-cubi |
|---|---|---|
| Pre-Push-Checks | CI-Checks lokal mit Live-Log, Abbruch, Push-Gate, Push und PR per Button | neu |
| GitHub | Workflow-Runs (Details, Log fehlgeschlagener Schritte, Neustart), Pull Requests (Details, Checks, Diff, Entwurf umschalten), Issues (Titel, Beschreibung, Labels, Zuweisung, Schließen/Öffnen, Kommentar), Kanban-Board (Verschieben) | cubi github |
| ArgoCD | Apps mit Kennzahlen, Filter (alle, Probleme, Projekt), Details, Sync (auch mehrere), Refresh, Hard Refresh, Diff, Historie, letzte Commits der Quelle, Kontext wechseln | cubi argocd |
| ArgoCD · Auto-Sync | Auto-Sync deaktivieren und wiederherstellen, gemerkt in der ConfigMap cubi-state |
cubi autosync |
| ArgoCD · Feature-Testing | targetRevision umstellen oder auf main zurücksetzen, mit Prüfung, ob der Branch existiert |
cubi feature-testing |
| ArgoCD · Pods skalieren | auf 0 oder eine eigene Anzahl stellen, wiederherstellen | cubi scale |
| Kubernetes | Pods (Logs, Logs folgen, Describe, Shell, Löschen), Nodes, Warnungen, Kontext und Namespace wechseln | cubi kubernetes |
| Helm | Releases mit Status, Values, Historie | cubi helm |
| Connect | SSH-Ziele aus targets.yaml als Karten |
cubi connect |
| Tailscale | Geräte, Ping, SSH, Up/Down, Status roh | cubi tailscale |
| Login | Anmeldestatus von ArgoCD, GitHub, Tailscale samt Login-Befehlen | cubi login |
| Tokens | Token-Register: Ablauf, Details, Runbook, Rotation, Datum eintragen, Register prüfen | cubi tokens |
Die Logik ist aus dem Python-cubi übernommen: dieselben Befehle, dieselben ApplicationSet-Regeln (ignoreApplicationDifferences), derselbe Zustand in cubi-state und dieselbe Nachprüfung nach 8 Sekunden. Terminal-cubi und cubi-desktop lassen sich deshalb abwechselnd benutzen.
Interaktive Befehle laufen in einem Terminalfenster: SSH, Pod-Shell, Logs folgen, argocd login, gh auth login, tailscale up/login und die Rotationsskripte. Das Fenster bleibt nach dem Ende offen und zeigt den Exit-Code. Alle anderen Befehle laufen im Hintergrund, die Ausgabe erscheint in einem eigenen Fenster mit Kopier-Button. Jede ändernde Aktion braucht eine Bestätigung.
Architektur
flowchart LR
APP[app.rs: Seitenleiste, Theme] --> V[views/*.rs: ein View je Bereich]
V --> T[ui/mod.rs: Task, Tabellen, Karten, Dialoge]
V --> L[argo.rs, tokens.rs: Logik aus dem Python-cubi]
V --> SH[shell.rs: Prozesse ohne Shell, Terminal]
SH --> CLI[kubectl, argocd, gh, helm, tailscale, ssh, git]
V --> PC[precheck/: Profile, Runner, Git, PR-Vorschläge]
Datei (cubi-desktop/src/) |
Aufgabe |
|---|---|
app.rs, main.rs |
Fenster, Seitenleiste, Argumente, --cli |
ui/mod.rs |
Theme, Hintergrund-Tasks, Tabellen, Status-Pills, Ausgabefenster, Bestätigungsdialog |
views/*.rs |
je Bereich ein View: precheck, github, argocd, kube, helm, connect, tailscale, login, tokens |
argo.rs |
ArgoCD-Apps, cubi-state, ApplicationSet-Regeln, Pläne und Anwendung für Auto-Sync, Feature-Testing, Skalieren, Token-Status |
tokens.rs |
Token-Register lesen, Fälligkeit, Datum atomar schreiben, Runbook-Abschnitt |
shell.rs |
Prozesse mit Zeitlimit, Fehlerzeile, Terminal starten |
cubi_config.rs |
targets.yaml suchen und lesen |
precheck/config.rs |
Profile laden und prüfen (unbekannte Felder und Platzhalter werden abgelehnt) |
precheck/runner.rs |
Voraussetzungen, Pfadfilter, Prozesse, Logs, Abbruch, Zeitlimit, Push-Gate |
precheck/git.rs, precheck/suggest.rs |
Repo-Status, Push, gh pr create, PR-Titel und -Text |
Warum egui und nicht Tauri: egui ist reines Rust, ohne JS-Frontend und ohne WebView-Dev-Pakete. Logs aus den tokio-Kanälen werden im Immediate-Mode direkt neu gezeichnet. Tauri lohnt sich erst bei einer aufwendigen Web-Oberfläche.
Externe Programme laufen über tokio::process::Command mit Argumentlisten, nie als Shell-String. Im Terminal wird das Kommando als Positionsparameter an sh -c '"$@"; …' übergeben, also ebenfalls ohne Interpolation. Ein Pre-Push-Check läuft in einer eigenen Prozessgruppe. Beim Abbruch bekommt die Gruppe erst SIGTERM und nach 5 Sekunden SIGKILL, so werden auch Kindprozesse von act und docker beendet.
Installation
cubi-desktop läuft unter Linux und macOS (Apple Silicon und Intel). Ein Skript installiert die App auf beiden Systemen wie eine normale Desktop-App mit Icon:
cd ~/git/github/tools/cubi/cubi-desktop
./install.sh # fehlende Pakete (mit Rückfrage), bauen, installieren, Schreibtisch-Symbol
./install.sh --yes # fehlende Pakete ohne Rückfrage
./install.sh --no-deps # Pakete nicht prüfen
./install.sh --no-desktop # ohne Symbol auf dem Schreibtisch
./install.sh --uninstall # App, Starter und Icons entfernen, Konfiguration bleibt
./deps.sh --check # nur anzeigen, welche Programme fehlen
Pakete
install.sh ruft zuerst deps.sh auf. Das Skript prüft alle Programme aus der Tabelle Voraussetzungen, zeigt die fehlenden an und installiert sie nach Rückfrage:
| Programm | Linux | macOS |
|---|---|---|
| Rust | offizieller rustup-Installer | brew install rustup |
| git, gh, ssh, curl, make, python3, PyYAML, npm, yamllint, ansible-lint, Docker | apt (docker.io, python3-yaml, openssh-client …) |
Homebrew bzw. Xcode Command Line Tools, Docker Desktop als Cask |
| kubectl, helm, argocd, act | offizielles Release-Binary nach ~/.local/bin, SHA-256 geprüft |
Homebrew |
| gitleaks | apt, sonst Release-Binary mit SHA-256-Prüfung |
Homebrew |
| Tailscale | offizieller Installer von tailscale.com | Tailscale-App als Cask |
| xcodegen | – | Homebrew |
Eine falsche Prüfsumme bricht die Installation ab. Für apt fragt sudo nach dem Passwort. CodeQL für die optionalen CodeQL-Checks wird nicht automatisch installiert. Am Ende nennt das Skript offene Schritte, z. B. sudo tailscale up oder die Aufnahme in die Gruppe docker.
| System | Ergebnis |
|---|---|
| Linux | ~/.local/bin/cubi-desktop, Eintrag „cubi“ im Anwendungsmenü (~/.local/share/applications/cubi-desktop.desktop), Icons in ~/.local/share/icons/hicolor, Symbol auf dem Schreibtisch. Unter GNOME das Symbol beim ersten Mal per Rechtsklick „Start erlauben“. |
| macOS | ~/Applications/cubi.app mit Icon, startbar über Launchpad und Spotlight, Verknüpfung auf dem Schreibtisch. Fürs Dock: App starten, Rechtsklick aufs Dock-Symbol, „Im Dock behalten“. |
Das Skript kopiert die Konfiguration nach ~/.config/cubi-desktop/, auf beiden Systemen derselbe Ort (oder $XDG_CONFIG_HOME/cubi-desktop/). Vorhandene Dateien überschreibt es nicht. Nach einem git pull installiert ein erneutes ./install.sh die neue Version.
Aus dem Terminal startet die App mit cubi-desktop, siehe Nutzung.
Umgebung beim Start aus Menü, Dock oder Launchpad
Eine App aus dem Startmenü bekommt nicht die Variablen aus ~/.bashrc oder ~/.zshrc, z. B. ein dort gesetztes KUBECONFIG. Ohne KUBECONFIG fällt kubectl auf localhost:8080 zurück, und ArgoCD, Kubernetes und Helm melden „connection refused“.
cubi-desktop liest deshalb beim Start einmal die Umgebung der interaktiven Login-Shell. Die Shell läuft dabei mit Zeitlimit und ohne Steuerterminal. Übernommen werden nur diese Variablen:
PATH, zusammengeführt mit/opt/homebrew/bin,/usr/local/bin,~/.local/binund~/.cargo/binKUBECONFIG,SSH_AUTH_SOCK,DOCKER_HOST,CUBI_CONFIG- alle mit
ARGOCD_,GH_,GITHUB_,HELM_,KUBE,TAILSCALE_oderHOMEBREW_am Anfang
Schon gesetzte Werte haben Vorrang. Feste Werte stehen in desktop.toml unter [env]:
[env]
KUBECONFIG = "~/.kube/homeserver.yaml"
macOS
- Tailscale: Die App nutzt die CLI aus
/Applications/Tailscale.app, wenntailscalenicht imPATHliegt. - Terminal: Interaktive Befehle öffnen Terminal.app über ein temporäres
.command-Skript. Die Argumente werden darin einzeln in Anführungszeichen gesetzt, das Skript löscht sich beim Start selbst. Für iTerm indesktop.tomlterminal = ["open", "-a", "iTerm"]setzen. - Pre-Push-Checks: Der Build von capulus-ios läuft hier echt, mit
xcodegenund Xcode. Für die act-Checks muss Docker Desktop laufen.
Linux
Zum Bauen braucht es nur einen C-Linker (build-essential). Die Grafikbibliotheken lädt die App zur Laufzeit, sie sind auf jedem Desktop vorhanden.
Das Terminal sucht die App in dieser Reihenfolge: x-terminal-emulator, gnome-terminal, konsole, xfce4-terminal, kitty, alacritty, xterm.
Voraussetzungen
| Voraussetzung | Wofür |
|---|---|
Rust stable (rustup) |
Build |
kubectl, argocd, helm, gh, tailscale, ssh |
cubi-Bereiche, wie beim Terminal-cubi |
| ein Terminal (Linux: siehe oben, macOS: Terminal.app oder iTerm) | interaktive Befehle |
git, gh (angemeldet mit gh auth login) |
Status, Push, PR |
Docker (Daemon läuft), act |
Workflow-Jobs mit Inline-Skript (capulus-core) und docker build |
yamllint, ansible-lint, gitleaks, npx, python3 mit PyYAML |
Checks der Profile |
codeql |
optionale CodeQL-Checks |
macOS mit xcodegen und Xcode |
Build von capulus-ios |
Fehlende Programme meldet die App selbst: in den cubi-Bereichen als Fehlermeldung, bei den Pre-Push-Checks als „Voraussetzung fehlt“. Installiert werden sie über install.sh bzw. deps.sh, die App selbst installiert nichts.
Nutzung
cubi-desktop # Oberfläche, Startbereich Pre-Push-Checks
cubi-desktop --bereich argocd # direkt in einen Bereich (Aliase wie bei cubi: sync, ft, scale, k8s, gh …)
cubi-desktop ~/git/github/capulus/capulus-core # Pre-Push-Checks für dieses Repo
cubi-desktop --cli . # Checks ohne Oberfläche, Exit-Code 0 = Pflicht-Checks grün
Die folgenden Schritte beschreiben die Pre-Push-Checks.
- Repo wählen: aus der Liste in
precheck/config.toml, als Pfad eingeben, oder die App im Repo starten. Oben stehen Remote, Profil, Branch, HEAD, Abstand zum Upstream, geänderte Dateien, Commits seit der Basis und dergh-Status. - Alle Checks starten oder einen einzelnen Check mit ▶ starten. Vorher holt die App
origin/<base_branch>und bestimmt die merge-base. Gegen sie laufen Pfadfilter, gitleaks und commitlint. - Links stehen Status und Laufzeit, rechts das Live-Log des gewählten Checks. Abbrechen beendet alle laufenden Checks.
- Push (
git push --set-upstream origin <branch>) ist nur aktiv, wenn- alle Pflicht-Checks
okoder per Pfadfilter übersprungen sind, - sich HEAD und Arbeitsverzeichnis seit dem Lauf nicht geändert haben,
- es keine nicht committeten Änderungen gibt.
- alle Pflicht-Checks
- Push trotzdem … öffnet einen Dialog mit allen offenen Bedingungen. Der Push geht erst, wenn man dort ausdrücklich bestätigt. Der Override wird im Aktionslog vermerkt.
- PR erstellen (
gh pr create) geht, sobald der Branch gepusht ist. Der Titel wird im Conventional-Commits-Format vorgeschlagen, mit dem Projekt als Scope. Die Beschreibung listet die Commits und das Ergebnis der lokalen Checks. Beides lässt sich vorher bearbeiten. Existiert schon ein PR, zeigt die App den Link.
Steht das Repo auf main (allgemein: auf einem Branch aus protected_branches), ist der Push gesperrt. Die App schlägt dann einen Branch-Namen vor (<typ>/<slug> aus dem letzten Commit) und legt ihn per git switch -c an.
Status
| Status | Bedeutung | Gibt Push frei |
|---|---|---|
| ok | alle Schritte mit Exit-Code 0 | ja |
| übersprungen | Pfadfilter wie in der CI, oder keine Commits gegenüber der Basis | ja |
| fehlgeschlagen | Exit-Code ≠ 0 oder Zeitlimit überschritten | nein |
| Voraussetzung fehlt | Tool fehlt, Docker läuft nicht, falsches Betriebssystem, Probe fehlgeschlagen | nein |
| abgebrochen | per Button abgebrochen | nein |
| wartet / läuft | noch nicht fertig | nein |
Optionale Checks (required = false, kursiv dargestellt) sperren den Push nie.
Konfiguration
Ordner: ~/.config/cubi-desktop/ (oder --config <ordner> oder CUBI_DESKTOP_CONFIG). Die cubi-Bereiche lesen dieselbe targets.yaml wie das Terminal-cubi (CUBI_CONFIG, ~/.config/cubi/targets.yaml, config/targets.yaml im cubi-Repo).
| Datei | Inhalt |
|---|---|
desktop.toml |
terminal: Terminal für interaktive Befehle als Argumentliste, z. B. ["gnome-terminal", "--"] oder unter macOS ["open", "-a", "iTerm"]. Leer heißt automatisch: Linux sucht ein Terminal, macOS nimmt Terminal.app. |
precheck/config.toml |
parallel (gleichzeitige Checks, Standard 2), repos (Liste für die Auswahl, ~ erlaubt) |
precheck/profiles/<name>.toml |
ein Profil pro Repo. Es wird über remote = "owner/repo" dem Remote origin zugeordnet. |
precheck/shared/commitlint.config.cjs |
commitlint-Regeln aus pkr-lab/.github (v1.2.0) |
Profil
| Schlüssel | Standard | Bedeutung |
|---|---|---|
name |
– | Projektname, auch der Scope im PR-Titel |
remote |
– | owner/repo |
base_branch |
main |
Ziel-Branch für merge-base und PR |
protected_branches |
["main"] |
Push gesperrt |
[[checks]] |
– | Liste der Checks |
Check
| Schlüssel | Standard | Bedeutung |
|---|---|---|
id, name |
– | eindeutige ID (a-z0-9-_:.), Anzeigename |
source |
leer | Herkunft in der CI, z. B. .github/workflows/ci.yml#lint |
required |
true |
Pflicht-Check |
steps |
– | Liste von Argumentlisten, laufen nacheinander im Repo, ohne Shell |
needs |
[] |
Programme im PATH |
needs_docker |
false |
docker info muss funktionieren |
os |
alle | linux, macos, windows |
probes |
[] |
{ cmd = [...], hint = "..." }. Schlägt die Probe fehl, wird hint als fehlende Voraussetzung angezeigt. |
paths |
alle | Globs. Läuft nur, wenn eine geänderte Datei passt. |
paths_ignore |
keine | Globs. Wird übersprungen, wenn alle Änderungen passen. |
skip_if_no_commits |
false |
überspringen, wenn HEAD gleich der merge-base ist |
env |
{} |
zusätzliche Umgebungsvariablen |
timeout_secs |
3600 |
Zeitlimit für den ganzen Check |
Platzhalter in Argumenten (nicht im Programmnamen): {repo}, {base}, {head}, {tmp}, {config_dir}. „Geänderte Dateien“ sind base..HEAD, plus nicht committete und unversionierte Dateien.
Neues Repo: Profil anlegen, Pfad in precheck/config.toml eintragen, fertig. Code ändert sich dafür nicht.
Mitgelieferte Profile
Abgeleitet aus den Workflows, die bei pull_request auf main laufen. Nicht übernommen sind Workflows, die nur auf main, nach Zeitplan oder per Hand laufen: release, mirror-gitlab, renovate, promote-*, sync-entw, entw-trigger, token-watch, security-issues, tailscale-poc und image-scan.
capulus-core
| Check | CI-Job | Lokal | Pflicht |
|---|---|---|---|
lint |
ci.yml#lint |
make lint. Braucht helm, denn das Makefile überspringt helm lint sonst stillschweigend. |
ja |
manifest-validate |
ci.yml#manifest-validate |
act -j manifest-validate |
ja |
go-check |
ci.yml#go-check |
act -j go-check |
ja |
isc-news-bot |
ci.yml#isc-news-bot |
act -j isc-news-bot |
ja |
token-register |
ci.yml#token-register |
python3 scripts/check-token-register.py |
ja |
secret-scan |
ci.yml#secret-scan |
gitleaks git über base..HEAD mit .gitleaks.toml und .gitleaksignore |
ja |
commitlint |
commitlint.yml |
npx @commitlint/cli über base..HEAD |
ja |
build-<app> (6×) |
build-images.yml#build |
docker build ohne Push, nur bei Änderungen unter dem App-Pfad |
ja |
codeql-<sprache> (4×) |
codeql.yml |
codeql database create/analyze, Ergebnis als CSV im Log |
nein |
capulus-ansible
| Check | CI-Job | Lokal | Pflicht |
|---|---|---|---|
lint |
ci.yml#lint |
ansible-galaxy collection install -r requirements.yml, dann make lint |
ja |
ca-checksum |
ci.yml#ca-checksum |
Root-CA von capulus-core main per curl, dann cmp |
ja |
secret-scan |
ci.yml#secret-scan |
gitleaks git |
ja |
commitlint |
commitlint.yml |
npx @commitlint/cli |
ja |
capulus-ios
| Check | CI-Job | Lokal | Pflicht |
|---|---|---|---|
build |
ci.yml#build |
xcodegen generate, dann xcodebuild build. Nur auf macOS. |
ja |
ca-checksum |
ci.yml#ca-checksum |
wie bei capulus-ansible, mit Resources/homeserver-root-ca.pem |
ja |
secret-scan |
ci.yml#secret-scan |
gitleaks git |
ja |
commitlint |
commitlint.yml |
npx @commitlint/cli |
ja |
codeql-actions, codeql-swift |
codeql.yml |
CodeQL, Swift nur auf macOS | nein |
Warum diese Ausführungsart:
- Jobs mit Inline-Skript im Workflow laufen über
act. So wird nichts nachgebaut und eine Änderung am Workflow wirkt sofort.actnutzt das Imagecatthehacker/ubuntu:act-latest. gitleaks-actionbraucht unteractein Token und für Organisationen eine Lizenz. Darum ruft die App das gitleaks-Programm direkt auf, mit derselben Konfiguration.
Unterschiede zur CI:
- Lokal wird das Arbeitsverzeichnis geprüft, nicht der Merge-Commit des PRs.
- Das Push-Gate verlangt deshalb ein sauberes Arbeitsverzeichnis.
Debugging und Fehlersuche
| Meldung | Ursache | Lösung |
|---|---|---|
Konfiguration: Profilordner … fehlt |
Konfiguration nicht kopiert | cp -r config/* ~/.config/cubi-desktop/ |
Kein Profil für owner/repo |
kein Profil mit passendem remote |
Profil anlegen |
The connection to the server localhost:8080 was refused |
kubectl findet keine kubeconfig, z. B. weil KUBECONFIG nur in einer Datei steht, die die Shell beim Start nicht liest |
KUBECONFIG in ~/.bashrc/~/.zshrc exportieren oder in desktop.toml unter [env] setzen, App neu starten |
Kein Terminal gefunden |
kein bekanntes Terminal im PATH |
terminal in desktop.toml setzen |
cubi-Konfiguration: Keine targets.yaml gefunden |
cubi nicht eingerichtet | ~/.config/cubi/targets.yaml anlegen, siehe Konfiguration |
Tool nicht installiert: … |
Programm fehlt im PATH |
installieren und den Check neu starten |
Docker läuft nicht … |
docker info schlägt fehl |
Docker starten, Benutzer in der Gruppe docker |
benötigt Betriebssystem macos |
iOS-Build unter Linux | auf dem Mac ausführen oder per Override pushen |
Warnung: git fetch fehlgeschlagen … |
offline | Die App nutzt den lokalen Stand von origin/<base>. |
Stand hat sich seit dem Lauf geändert |
Commit oder Änderung nach dem Lauf | Checks neu starten |
gh ist nicht angemeldet |
kein gh-Login | gh auth login |
| act fragt nach einem Image oder hängt beim ersten Lauf | Image wird geladen (mehrere GB) | einmalig docker pull catthehacker/ubuntu:act-latest |
Mit --cli laufen dieselben Checks im Terminal. Jede Logzeile hat dort das Präfix [check-id].