Skip to content

CLAUDE.md

Latest commit

 

History

History
240 lines (171 loc) · 8.11 KB

CLAUDE.md

File metadata and controls

240 lines (171 loc) · 8.11 KB
Raw

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)

Command Description
make dev Start Tauri development environment
make web-dev Start Vite only (no Tauri)
make build Build production Tauri app (macOS)
make build-windows Cross-compile Windows NSIS installer from macOS
make build-all Build macOS and Windows installers (Linux built by CI)
make lint Run ESLint
make format Format code with Prettier
make check Run TypeScript type checking
make rust-check Check Rust code
make rust-fmt Format Rust code
make clean Clean build artifacts
make install Install all dependencies (incl. vet if Python available)
make vet AI code review of all branch changes against main
make vet-install Install vet CLI for AI code verification
make help Show all available commands

Release & Deploy

Command Description
make release Release via CI: version bump, AI-generated changelog, commit, tag push → CI builds all platforms
make release-push Review and publish a prepared release after explicit terminal confirmation
make release-ai-dry-run Test Claude, Codex, and OpenCode release integration without changing release files
make release-changelog-dry-run Test the real Claude → Codex → OpenCode fallback chain without changing release files
make release-manual-dry-run Test the Markdown prompt and terminal paste fallback without changing release files
make build-deploy Alias for make release

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

Skill Purpose Usage
/software-design-review Analyzes code against 15 Ousterhout principles /software-design-review src/lib/stores/cluster-store.ts
/refactor Strategic refactoring with safety-first approach /refactor src/lib/stores/cluster-store.ts
/humanizer Remove AI writing patterns from text /humanizer

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