pilot/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

**Pilot** is an MQTT-based PC control agent for Home Assistant. It publishes system telemetry (CPU, memory, battery, IP) and exposes commands (shutdown, reboot, sleep, screen control) via MQTT. The project has two versions:

- **v1 (Python)**: Legacy implementation in [main.py](main.py), [main_prog.py](main_prog.py), [main-lenovo-bureau.py](main-lenovo-bureau.py)
- **v2 (Rust)**: Active rewrite in [pilot-v2/](pilot-v2/) with improved architecture, unified MQTT contract, and platform abstraction

The v2 rewrite aims to fix v1's hardcoded configuration, lack of authentication/TLS, missing LWT, and OS-specific logic scattered across scripts.

## Development Commands

### V2 (Rust - Active Development)

```bash
# Run unit tests
cd pilot-v2 && cargo test

# Build release binary
cd pilot-v2 && cargo build --release

# Run locally (auto-creates config.yaml from example)
./scripts/run_pilot.sh

# Run in pilot-v2 directory directly
cd pilot-v2 && cargo run
```

### V1 (Python - Legacy)

```bash
# Activate Python virtual environment
source monenv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run manually (v1)
python3 main.py

# Deactivate virtual environment
deactivate
```

### Testing

```bash
# Send MQTT commands using helper script
python3 scripts/mqtt_send.py --device <device_name> --action shutdown --value OFF
python3 scripts/mqtt_send.py --device <device_name> --action screen --value ON

# Manual MQTT testing
# See docs/tests_mqtt.md for detailed checklist
```

## Architecture (V2)

### Module Structure

The v2 codebase follows a clean modular architecture in [pilot-v2/src/](pilot-v2/src/):

- **[config/](pilot-v2/src/config/)**: YAML configuration loading and validation
- **[mqtt/](pilot-v2/src/mqtt/)**: MQTT client, connection handling, pub/sub logic
- **[ha/](pilot-v2/src/ha/)**: Home Assistant discovery payload generation
- **[telemetry/](pilot-v2/src/telemetry/)**: System metrics collection (CPU, memory, temperature, IP)
- **[commands/](pilot-v2/src/commands/)**: Command parsing, allowlist validation, cooldown logic
- **[platform/](pilot-v2/src/platform/)**: OS-specific backends for power and screen control
  - [platform/linux/](pilot-v2/src/platform/linux/): logind/polkit, sudoers, GNOME busctl, X11 xset
  - [platform/windows/](pilot-v2/src/platform/windows/): Windows service, WinAPI session
- **[runtime/](pilot-v2/src/runtime/)**: Main event loop orchestration (telemetry ticks, heartbeat, command handling)
- **[security/](pilot-v2/src/security/)**: Security utilities (future: auth/TLS validation)

### MQTT Contract (V2)

Base topic: `pilot/<device>/...`

**Topics:**
- `pilot/<device>/availability`: online/offline (LWT support)
- `pilot/<device>/status`: JSON with version, OS, uptime, backends
- `pilot/<device>/capabilities`: JSON listing enabled features
- `pilot/<device>/state/<name>`: Sensor states (cpu_usage, memory, power_state, etc.)
- `pilot/<device>/cmd/<action>/set`: Command topics (shutdown, reboot, sleep, screen)

**Home Assistant Discovery:**
- Prefix: `homeassistant`
- Conforms to HA discovery spec with device_info, unique_id, state_topic, command_topic

### Runtime Flow

The [runtime/mod.rs:31-127](pilot-v2/src/runtime/mod.rs#L31-L127) orchestrates:

1. **Startup**: Connect to MQTT, publish availability/status/capabilities, send HA discovery, subscribe to commands
2. **Event Loop** (tokio::select):
   - Telemetry tick: Read metrics from providers, publish to `state/<name>` topics
   - Heartbeat tick: Publish status and power_state
   - MQTT events: Handle incoming commands with cooldown and allowlist checks
   - Shutdown signal: Publish offline availability, disconnect gracefully

3. **Command Handling**: Parse action/value, check allowlist, enforce cooldown, execute via platform backend, publish state updates

## Configuration (V2)

Config file locations (searched in order):
- Linux: `/etc/pilot/config.yaml` then `./config.yaml`
- Windows: `C:\ProgramData\Pilot\config.yaml` then `./config.yaml`

Example: [config/config.example.yaml](config/config.example.yaml)

Key fields:
- `device.name`: Device identifier (used in MQTT topics)
- `mqtt`: Broker connection details, QoS, retain settings
- `features.telemetry`: Enable/disable, interval
- `features.commands`: Enable/disable, cooldown, dry_run mode, allowlist
- `power_backend.linux/windows`: Backend selection (logind_polkit, sudoers, etc.)
- `screen_backend.linux/windows`: Backend selection (gnome_busctl, x11_xset, etc.)

## Platform Backends

Backends are selected via config and abstracted behind traits:

- **PowerControl**: shutdown, reboot, sleep, hibernate
- **ScreenControl**: screen_on, screen_off

Linux backends require appropriate permissions:
- `linux_sudoers`: Requires sudoers entries for `/sbin/shutdown`, `/sbin/reboot`
- `gnome_busctl`: Requires active GNOME session and user DBus access

See [docs/deploiement.md](docs/deploiement.md) for permission setup details.

## Documentation

Key docs in [docs/](docs/):
- [analyse_v1.md](docs/analyse_v1.md): V1 analysis (hardcoded config, security issues)
- [architecture_v2.md](docs/architecture_v2.md): V2 architecture diagram and MQTT contract
- [deploiement.md](docs/deploiement.md): Deployment guide (systemd service, permissions)
- [tests_mqtt.md](docs/tests_mqtt.md): Manual MQTT testing checklist
- [utilisation.md](docs/utilisation.md): Usage instructions

## Important Notes

- **Active development is on v2 (Rust)**. Only fix critical bugs in v1 Python scripts.
- **Dry-run mode**: Set `features.commands.dry_run: true` in config to test without executing system commands
- **Security**: V1 lacks auth/TLS. V2 architecture supports it but not yet implemented.
- **Testing**: Always test commands in dry-run mode first. Use [scripts/mqtt_send.py](scripts/mqtt_send.py) for manual testing.
- **Systemd service**: V1 uses [mqtt_pilot.service](mqtt_pilot.service), V2 will use `packaging/pilot.service`
- **Backups**: V1 backups are in [backup_v1/](backup_v1/)