PKR-Lab

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.

cubi-desktop: Pre-Push-Checks

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.

cubi-desktop: GitHub-Workflow-Runs

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.

cubi-Icon

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:

Schon gesetzte Werte haben Vorrang. Feste Werte stehen in desktop.toml unter [env]:

[env]
KUBECONFIG = "~/.kube/homeserver.yaml"

macOS

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.

  1. 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 der gh-Status.
  2. 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.
  3. Links stehen Status und Laufzeit, rechts das Live-Log des gewählten Checks. Abbrechen beendet alle laufenden Checks.
  4. Push (git push --set-upstream origin <branch>) ist nur aktiv, wenn
    • alle Pflicht-Checks ok oder per Pfadfilter übersprungen sind,
    • sich HEAD und Arbeitsverzeichnis seit dem Lauf nicht geändert haben,
    • es keine nicht committeten Änderungen gibt.
  5. 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.
  6. 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:

Unterschiede zur CI:


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