Kubeli - Kubernetes Management Desktop App

Project Overview

Kubeli is a modern Kubernetes management desktop application built with:

• Frontend: Vite + React 19
• Desktop: Tauri 2.9 (Rust backend)
• State: Zustand
• Styling: Tailwind CSS
• K8s Client: kube-rs (Rust)

Quick Start

# Development (Tauri + Vite)
make dev

# Web only development
make web-dev

# Production build
make build

Development Commands

Using Make (Recommended)

Release & Deploy

The release flow: make release → changelog generation tries Claude, then Codex, then OpenCode → if all CLIs fail, .changelog-ai-prompt.md is created for use in any AI chat and the generated bullet points can be pasted back into the terminal → release files and notes are shown for review → pressing Enter confirms commit, push, and tag creation; any other input aborts → tag push triggers GitHub Actions → builds macOS (ARM + x86), Windows, Linux → waits for manual approval → deploys to FTP + publishes GitHub Release. After an abort, edit the prepared files and run make release-push to review and continue without another version bump.

npm scripts are listed in package.json; Rust uses the standard cargo commands in src-tauri/.

Architecture

Frontend (TypeScript/React)

• Zustand stores manage application state
• Tauri commands are invoked via @/lib/tauri/commands.ts
• Types are shared between frontend and backend

Backend (Rust)

• AppState holds the thread-safe KubeClientManager
• KubeConfig parses kubeconfig files
• Commands expose functionality to frontend

Local Kubernetes Testing

# Start minikube with addons and sample resources
make minikube-start

# Check status (includes sample resource count)
make minikube-status

# Apply/refresh sample resources manually
make minikube-setup-samples

# Remove sample resources
make minikube-clean-samples

# List resources
make k8s-pods
make k8s-services
make k8s-namespaces

OIDC sign-in testing

make oidc-dev        # local OIDC stack: HTTPS Dex + minikube that trusts it
make oidc-dev-stop   # tear it down

Brings up a local Dex provider and a dedicated minikube profile so a Kubeli OIDC sign-in connects all the way through. See .dev/oidc/README.md for details (needs a build for the kubeli:// callback, and one /etc/hosts line via sudo).

Sample Resources (kubeli-demo namespace)

The make minikube-start command automatically creates sample Kubernetes resources covering all major workload and policy types. The manifests (and the authoritative list of what gets created) live in .dev/k8s-samples/.

Windows Development

Building for Windows (from macOS)

# Install cross-compile dependencies (one-time)
make install-windows-build-deps

# Build Windows NSIS installer
make build-windows

# Build both macOS and Windows
make build-all

Output: src-tauri/target/x86_64-pc-windows-msvc/release/bundle/nsis/Kubeli_*_x64-setup.exe

Windows VM Testing

For testing in Windows VMs (UTM, VirtualBox) without nested virtualization:

# On Mac: Expose minikube API
make minikube-serve

# On Windows: Connect to Mac's minikube
.\connect-minikube.ps1 -HostIP <mac-ip>

See .dev/windows/WINDOWS-SETUP.md for full documentation.

Platform Detection

Use the usePlatform hook for OS-specific behavior:

import { usePlatform } from "@/lib/hooks/usePlatform";

function MyComponent() {
  const { isMac, isWindows, modKeySymbol } = usePlatform();

  // modKeySymbol: "⌘" on Mac, "Ctrl+" on Windows/Linux
  return <Kbd>{modKeySymbol}S</Kbd>;
}

The full property list is in src/lib/hooks/usePlatform.ts.

Key Files

• src/lib/stores/cluster-store.ts - Cluster state management
• src/lib/tauri/commands.ts - Tauri command bindings
• src-tauri/src/commands/clusters.rs - Cluster command handlers
• src-tauri/src/k8s/client.rs - Kubernetes client manager
• src-tauri/src/k8s/config.rs - Kubeconfig parsing

Testing Rule

• Every bug fix must include a regression test when technically feasible.
• The test should cover the failure mode that caused the bug, not just the happy path.
• If a regression test is not feasible, document the reason clearly in the PR.

Code Quality Skills

This project includes custom Claude skills for code quality based on industry best practices.

Available Skills

/software-design-review (Analysis)

Based on John Ousterhout's "A Philosophy of Software Design". Checks for:

• Module Depth (Deep vs. Shallow)
• Information Hiding & Leaks
• Generalization vs. Specialization
• Error Handling (Define errors away)
• Consistency & Obviousness
• Strategic vs. Tactical Programming

/refactor (Action)

Combines Ousterhout principles with Clean Code (Robert Martin) smells. Includes:

• Phase 1-2: Analysis + Safety checklist (tests, git state)
• Phase 3: Clean Code smells (F1-F4, G1-G36, N1-N7, T1-T9)
• Phase 4: Stack-specific patterns (Vite/React, Zustand, Tauri/Rust)
• Phase 5-6: Workflow + Prioritization

Key rules enforced:

• Functions: Small, one task, max 3 args
• Law of Demeter: No train wrecks (a.b().c().d())
• DRY: No duplication
• F.I.R.S.T.: Fast, Independent, Repeatable, Self-validating, Timely tests
• Boy Scout Rule: Leave code cleaner than you found it

/humanizer (Writing Quality)

Detects and removes 24 common AI writing patterns (based on Wikipedia's "Signs of AI writing"). Use /humanizer when writing or editing:

• README, CHANGELOG, PR descriptions - user-facing documentation
• Landing page copy (web/) - marketing text on kubeli.dev
• Release notes (.release-notes.md) - announcement text
• CONTRIBUTING, SECURITY, AI_POLICY - community-facing docs

Not needed for code comments, commit messages, or internal CLAUDE.md notes.

Git Commit Guidelines

IMPORTANT: Do NOT add the following to commit messages:

• No "Generated with Claude Code" text
• No "Co-Authored-By: Claude" lines
• No emojis in commit messages
• Keep commit messages clean and concise

Resource Diagram (React Flow)

Design decisions, viewport rules and flicker-prevention patterns for the visual resource diagram live in src/components/features/visualization/CLAUDE.md (loaded automatically when working in that area).