govee 0.2.0

Async Rust library for controlling Govee smart lighting devices via cloud and local LAN APIs
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67

# govee

A Rust library for controlling Govee smart lighting devices. Provides idiomatic async access to both the Govee cloud API (v1) and the local LAN API over UDP, a unified backend abstraction, device registry with name/alias resolution, and a scene system for multi-device presets.

Designed as a foundation for `govee-cli`, `govee-server`, and `govee-mcp` — it has no opinion about how it is invoked.

## Status

**WIP**: This project is currently in development and not ready for production use.  
**Done**: [M1](#development-plan) in v0.1.0

## Getting started

### Prerequisites

- [Rust](https://www.rust-lang.org/tools/install) (1.85+ for edition 2024)
- [Lefthook](https://github.com/evilmartians/lefthook) — git hooks manager

### Set up git hooks

Install lefthook and activate the hooks before making any commits:

```sh
# macOS
brew install lefthook

# or via npm/cargo/go — see https://github.com/evilmartians/lefthook/blob/master/docs/install.md
```

```sh
lefthook install
```

This configures:
- **pre-commit** — `cargo fmt --check` and `cargo clippy` (parallel)
- **pre-push** — `cargo build` then `cargo test` (sequential)

### Build

```sh
cargo build
```

### Test

```sh
cargo test
```

### Lint

```sh
cargo fmt --check
cargo clippy
```

## Development plan

| Milestone | Scope | Status |
|-----------|-------|--------|
| **M1 — Scaffold & CI/CD** | Cargo project, module stubs, GitHub Actions for CI (fmt + clippy, build, test) and two-step immutable release on tag | v0.1.0 |
| **M2 — Core types & configuration** | `DeviceId`, `Device`, `DeviceState`, `Color`, `GoveeError`, `Config` with TOML parsing, input validation | Pending |
| **M3 — Cloud backend (v1)** | `GoveeBackend` trait, `CloudBackend` implementation (list, state, control), rate limit handling, wiremock tests | Pending |
| **M4 — Local LAN backend** | `LocalBackend` with UDP multicast discovery, unicast control, state queries, port conflict detection | Pending |
| **M5 — Device registry** | `DeviceRegistry`: cloud+local merge, name/alias resolution, backend auto-selection, optimistic state cache, groups | Pending |
| **M6 — Scenes & workflow stub** | Built-in + user-defined scene presets, `apply_scene`, workflow engine stub (`NotImplemented`) | Pending |
| **M7 — SRE & hardening** | Structured tracing, retry/backoff, graceful degradation, security audit, integration test suite, threat model docs | Pending |