69376b886f
Complete rebranding of all components: - Core miner: xmrig -> miner (binary, version.h, CMakeLists.txt) - Proxy: xmrig-proxy -> miner-proxy - CUDA plugin: xmrig-cuda -> miner-cuda - Heatmap: xmrig-nonces-heatmap -> miner-nonces-heatmap - Go CLI wrapper: miner-cli -> miner-ctrl Vendored XMRig ecosystem into miner/ directory: - miner/core - XMRig CPU/GPU miner - miner/proxy - Stratum proxy - miner/cuda - NVIDIA CUDA plugin - miner/heatmap - Nonce visualization tool - miner/config - Configuration UI - miner/deps - Pre-built dependencies Updated dev fee to use project wallet with opt-out (kMinimumDonateLevel=0) Updated branding to Lethean (domain, copyright, version 0.1.0) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
128 lines
5.3 KiB
Markdown
128 lines
5.3 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Build & Development Commands
|
|
|
|
```bash
|
|
# Build the CLI binary
|
|
make build # Outputs: miner-ctrl
|
|
|
|
# Run tests
|
|
make test # Tests with race detection and coverage
|
|
go test -v ./pkg/mining/... # Run tests for specific package
|
|
go test -run TestName ./... # Run a single test
|
|
|
|
# Lint and format
|
|
make lint # Runs fmt, vet, and golangci-lint
|
|
make fmt # Format code only
|
|
|
|
# Generate Swagger docs (required after API changes)
|
|
make docs # Runs: swag init -g ./cmd/mining/main.go
|
|
|
|
# Development server (builds, generates docs, starts server)
|
|
make dev # Starts on localhost:9090
|
|
|
|
# Build for all platforms
|
|
make build-all # Outputs to dist/
|
|
|
|
# Create release packages
|
|
make package # Uses GoReleaser snapshot
|
|
|
|
# E2E Tests (Playwright)
|
|
make e2e # Run all E2E tests
|
|
make e2e-api # Run API tests only (no browser)
|
|
make e2e-ui # Open Playwright UI for interactive testing
|
|
```
|
|
|
|
## Architecture Overview
|
|
|
|
### Go Backend (`pkg/mining/`)
|
|
|
|
The mining package provides a modular miner management system:
|
|
|
|
- **`mining.go`**: Core interfaces and types. The `Miner` interface defines the contract all miner implementations must follow (Install, Start, Stop, GetStats, etc.). Also contains `Config` for miner configuration and `PerformanceMetrics` for stats.
|
|
|
|
- **`miner.go`**: `BaseMiner` struct with shared functionality for all miners (binary discovery, installation from URL, archive extraction, hashrate history management). Uses XDG base directories via `github.com/adrg/xdg`.
|
|
|
|
- **`manager.go`**: `Manager` handles miner lifecycle. Maintains running miners in a map, supports autostart from config, runs background stats collection every 10 seconds. Key methods: `StartMiner()`, `StopMiner()`, `ListMiners()`.
|
|
|
|
- **`service.go`**: RESTful API using Gin. `Service` wraps the Manager and exposes HTTP endpoints under configurable namespace (default `/api/v1/mining`). Swagger docs generated via swaggo annotations.
|
|
|
|
- **`xmrig.go` / `xmrig_start.go` / `xmrig_stats.go`**: XMRig miner implementation. Downloads from GitHub releases, generates config JSON, polls local HTTP API for stats.
|
|
|
|
- **`profile_manager.go`**: Manages saved mining configurations (profiles). Stored in `~/.config/lethean-desktop/mining_profiles.json`.
|
|
|
|
- **`config_manager.go`**: Manages autostart settings and last-used configs for miners.
|
|
|
|
### CLI (`cmd/mining/`)
|
|
|
|
Cobra-based CLI. Commands in `cmd/mining/cmd/`:
|
|
- `serve` - Main command, starts REST API server with interactive shell
|
|
- `start/stop/status` - Miner control
|
|
- `install/uninstall/update` - Miner installation management
|
|
- `doctor` - Check miner installations
|
|
- `list` - List running/available miners
|
|
|
|
### Angular UI (`ui/`)
|
|
|
|
Angular 20+ frontend that builds to `mbe-mining-dashboard.js` web component. Communicates with the Go backend via the REST API.
|
|
|
|
```bash
|
|
cd ui
|
|
ng serve # Development server on :4200
|
|
ng build # Build to ui/dist/
|
|
ng test # Run unit tests (Karma/Jasmine)
|
|
npm run e2e # Run Playwright E2E tests
|
|
```
|
|
|
|
### E2E Tests (`ui/e2e/`)
|
|
|
|
Playwright-based E2E tests covering both API and UI:
|
|
|
|
- **`e2e/api/`**: API tests (no browser) - system endpoints, miners, profiles CRUD
|
|
- **`e2e/ui/`**: Browser tests - dashboard, profiles, admin, setup wizard
|
|
- **`e2e/page-objects/`**: Page object pattern for UI components
|
|
- **`e2e/fixtures/`**: Shared test data
|
|
|
|
Tests automatically start the Go backend and Angular dev server via `playwright.config.ts` webServer config.
|
|
|
|
### Desktop App (`cmd/desktop/mining-desktop/`)
|
|
|
|
Native desktop application using Wails v3 with Angular frontend. Embeds the mining backend into a standalone binary.
|
|
|
|
```bash
|
|
cd cmd/desktop/mining-desktop
|
|
|
|
# Build for current platform
|
|
wails3 build # Outputs: bin/mining-dashboard
|
|
|
|
# Development mode (hot reload)
|
|
wails3 dev
|
|
|
|
# Platform-specific builds (via Taskfile)
|
|
task linux:build # Linux binary
|
|
task windows:build # Windows .exe
|
|
task darwin:build # macOS binary
|
|
task darwin:package # macOS .app bundle
|
|
```
|
|
|
|
**Key files:**
|
|
- **`main.go`**: Wails app entry point, embeds Angular frontend via `//go:embed all:frontend/dist/browser`
|
|
- **`miningservice.go`**: Go service exposing mining functionality to frontend via Wails bindings
|
|
- **`frontend/bindings/`**: Auto-generated TypeScript bindings for calling Go methods
|
|
- **`build/`**: Platform-specific build configs (icons, manifests, installers)
|
|
|
|
**GitHub Actions:** `.github/workflows/desktop-release.yml` builds for all platforms on tag or manual dispatch.
|
|
|
|
## Key Patterns
|
|
|
|
- **Interface-based design**: `Miner` and `ManagerInterface` allow different miner implementations
|
|
- **XDG directories**: Config in `~/.config/lethean-desktop/`, data in `~/.local/share/lethean-desktop/miners/`
|
|
- **Hashrate history**: Two-tier storage - high-res (10s intervals, 5 min retention) and low-res (1 min averages, 24h retention)
|
|
- **Syslog integration**: Platform-specific logging via `syslog_unix.go` / `syslog_windows.go`
|
|
|
|
## API Documentation
|
|
|
|
When running `make dev`, Swagger UI is available at:
|
|
`http://localhost:9090/api/v1/mining/swagger/index.html`
|