refactor: comprehensive code quality, security, and release readiness improvements

Security: tighten CORS defaults, add webhook rate limiting, fix XSS in automations, guard WebSocket JSON.parse, validate ADB address input, seal debug exception leak, URL-encode WS tokens, CSS.escape in selectors. Code quality: add Pydantic models for brightness/power endpoints, fix thread safety and name uniqueness in DeviceStore, immutable update pattern, split 6 oversized files into 16 focused modules, enable TypeScript strictNullChecks (741→102 errors), type state variables, add dom-utils helper, migrate 3 modules from inline onclick to event delegation, ProcessorDependencies dataclass. Performance: async store saves, health endpoint log level, command palette debounce, optimized entity-events comparison, fix service worker precache list. Testing: expand from 45 to 293 passing tests — add store tests (141), route tests (25), core logic tests (42), E2E flow tests (33), organize into tests/api/, tests/storage/, tests/core/, tests/e2e/. DevOps: CI test pipeline, pre-commit config, Dockerfile multi-stage build with non-root user and health check, docker-compose improvements, version bump to 0.2.0. Docs: rewrite CLAUDE.md (202→56 lines), server/CLAUDE.md (212→76), create contexts/server-operations.md, fix .js→.ts references, fix env var prefix in README, rewrite INSTALLATION.md, add CONTRIBUTING.md and .env.example.
2026-03-22 00:38:28 +03:00
parent 07bb89e9b7
commit f2871319cb
115 changed files with 9808 additions and 5818 deletions
--- a/INSTALLATION.md
+++ b/INSTALLATION.md
@@ -1,281 +1,222 @@
 # Installation Guide

-Complete installation guide for WLED Screen Controller server and Home Assistant integration.
+Complete installation guide for LED Grab (WLED Screen Controller) server and Home Assistant integration.

 ## Table of Contents

-1. [Server Installation](#server-installation)
-2. [Home Assistant Integration](#home-assistant-integration)
-3. [Quick Start](#quick-start)
+1. [Docker Installation (recommended)](#docker-installation)
+2. [Manual Installation](#manual-installation)
+3. [First-Time Setup](#first-time-setup)
+4. [Home Assistant Integration](#home-assistant-integration)
+5. [Configuration Reference](#configuration-reference)
+6. [Troubleshooting](#troubleshooting)

 ---

-## Server Installation
+## Docker Installation

-### Option 1: Python (Development/Testing)
+The fastest way to get running. Requires [Docker](https://docs.docker.com/get-docker/) with Compose.

-**Requirements:**
- Python 3.11 or higher
- Windows, Linux, or macOS
+1. **Clone and start:**

-**Steps:**
+   ```bash
+   git clone https://git.dolgolyov-family.by/alexei.dolgolyov/wled-screen-controller-mixed.git
+   cd wled-screen-controller/server
+   docker compose up -d
+   ```
+
+2. **Verify:**
+
+   ```bash
+   curl http://localhost:8080/health
+   # → {"status":"healthy", ...}
+   ```
+
+3. **Open the dashboard:** <http://localhost:8080>
+
+4. **View logs:**
+
+   ```bash
+   docker compose logs -f
+   ```
+
+5. **Stop / restart:**
+
+   ```bash
+   docker compose down          # stop
+   docker compose up -d         # start again (data is persisted)
+   ```
+
+### Docker manual build (without Compose)
+
+```bash
+cd server
+docker build -t ledgrab .
+
+docker run -d \
+  --name wled-screen-controller \
+  -p 8080:8080 \
+  -v $(pwd)/data:/app/data \
+  -v $(pwd)/logs:/app/logs \
+  -v $(pwd)/config:/app/config:ro \
+  ledgrab
+```
+
+### Linux screen capture in Docker
+
+Screen capture from inside a container requires X11 access. Uncomment `network_mode: host` in `docker-compose.yml` and ensure the `DISPLAY` variable is set. Wayland is not currently supported for in-container capture.
+
+---
+
+## Manual Installation
+
+### Requirements
+
+| Dependency | Version | Purpose |
+| ---------- | ------- | ------- |
+| Python | 3.11+ | Backend server |
+| Node.js | 18+ | Frontend build (esbuild) |
+| pip | latest | Python package installer |
+| npm | latest | Node package manager |
+
+### Steps

 1. **Clone the repository:**
+
   ```bash
-   git clone https://github.com/yourusername/wled-screen-controller.git
+   git clone https://git.dolgolyov-family.by/alexei.dolgolyov/wled-screen-controller-mixed.git
   cd wled-screen-controller/server
   ```

-2. **Create virtual environment:**
+2. **Build the frontend bundle:**
+
+   ```bash
+   npm ci
+   npm run build
+   ```
+
+   This compiles TypeScript and bundles JS/CSS into `src/wled_controller/static/dist/`.
+
+3. **Create a virtual environment:**
+
   ```bash
   python -m venv venv

-   # Windows
+   # Linux / macOS
+   source venv/bin/activate
+
+   # Windows (cmd)
   venv\Scripts\activate

-   # Linux/Mac
-   source venv/bin/activate
+   # Windows (PowerShell)
+   venv\Scripts\Activate.ps1
   ```

-3. **Install dependencies:**
+4. **Install Python dependencies:**
+
   ```bash
   pip install .
   ```

-4. **Configure (optional):**
-   Edit `config/default_config.yaml` to customize settings.
+   Optional extras:

-5. **Run the server:**
   ```bash
-   # Set PYTHONPATH
-   export PYTHONPATH=$(pwd)/src  # Linux/Mac
-   set PYTHONPATH=%CD%\src        # Windows
+   pip install ".[camera]"          # Webcam capture via OpenCV
+   pip install ".[perf]"            # DXCam, BetterCam, WGC (Windows only)
+   pip install ".[notifications]"   # OS notification capture
+   pip install ".[dev]"             # pytest, black, ruff (development)
+   ```

-   # Start server
+5. **Set PYTHONPATH and start the server:**
+
+   ```bash
+   # Linux / macOS
+   export PYTHONPATH=$(pwd)/src
+   uvicorn wled_controller.main:app --host 0.0.0.0 --port 8080
+
+   # Windows (cmd)
+   set PYTHONPATH=%CD%\src
   uvicorn wled_controller.main:app --host 0.0.0.0 --port 8080
   ```

-6. **Verify:**
-   Open http://localhost:8080/docs in your browser.
+6. **Verify:** open <http://localhost:8080> in your browser.

-### Option 2: Docker (Recommended for Production)
+---

-**Requirements:**
- Docker
- Docker Compose
+## First-Time Setup

-**Steps:**
+### Change the default API key

-1. **Clone the repository:**
-   ```bash
-   git clone https://github.com/yourusername/wled-screen-controller.git
-   cd wled-screen-controller/server
-   ```
+The server ships with a development API key (`development-key-change-in-production`). **Change it before exposing the server on your network.**

-2. **Start with Docker Compose:**
-   ```bash
-   docker-compose up -d
-   ```
+Option A -- edit the config file:

-3. **View logs:**
-   ```bash
-   docker-compose logs -f
-   ```
+```yaml
+# server/config/default_config.yaml
+auth:
+  api_keys:
+    main: "your-secure-key-here"   # replace the dev key
+```

-4. **Verify:**
-   Open http://localhost:8080/docs in your browser.
-
-### Option 3: Docker (Manual Build)
+Option B -- set an environment variable:

 ```bash
-cd server
-docker build -t wled-screen-controller .
-
-docker run -d \
-  --name wled-controller \
-  -p 8080:8080 \
-  -v $(pwd)/data:/app/data \
-  -v $(pwd)/logs:/app/logs \
-  --network host \
-  wled-screen-controller
+export WLED_AUTH__API_KEYS__main="your-secure-key-here"
 ```

+Generate a random key:
+
+```bash
+openssl rand -hex 32
+```
+
+### Configure CORS for LAN access
+
+By default the server only allows requests from `http://localhost:8080`. To access the dashboard from another machine on your LAN, add its origin:
+
+```yaml
+# server/config/default_config.yaml
+server:
+  cors_origins:
+    - "http://localhost:8080"
+    - "http://192.168.1.100:8080"   # your server's LAN IP
+```
+
+Or via environment variable:
+
+```bash
+WLED_SERVER__CORS_ORIGINS='["http://localhost:8080","http://192.168.1.100:8080"]'
+```
+
+### Discover devices
+
+Open the dashboard and go to the **Devices** tab. Click **Discover** to find WLED devices on your network via mDNS. You can also add devices manually by IP address.
+
 ---

 ## Home Assistant Integration

-### Option 1: HACS (Recommended)
+### Option 1: HACS (recommended)

-1. **Install HACS** if not already installed:
-   - Follow instructions at https://hacs.xyz/docs/setup/download
+1. Install [HACS](https://hacs.xyz/docs/setup/download) if you have not already.
+2. Open HACS in Home Assistant.
+3. Click the three-dot menu, then **Custom repositories**.
+4. Add URL: `https://git.dolgolyov-family.by/alexei.dolgolyov/wled-screen-controller-mixed`
+5. Set category to **Integration** and click **Add**.
+6. Search for "WLED Screen Controller" in HACS and click **Download**.
+7. Restart Home Assistant.
+8. Go to **Settings > Devices & Services > Add Integration** and search for "WLED Screen Controller".
+9. Enter your server URL (e.g., `http://192.168.1.100:8080`) and API key.

-2. **Add Custom Repository:**
-   - Open HACS in Home Assistant
-   - Click the three dots menu → Custom repositories
-   - Add URL: `https://github.com/yourusername/wled-screen-controller`
-   - Category: Integration
-   - Click Add
+### Option 2: Manual

-3. **Install Integration:**
-   - In HACS, search for "WLED Screen Controller"
-   - Click Download
-   - Restart Home Assistant
+Copy the `custom_components/wled_screen_controller/` folder from this repository into your Home Assistant `config/custom_components/` directory, then restart Home Assistant and add the integration as above.

-4. **Configure Integration:**
-   - Go to Settings → Devices & Services
-   - Click "+ Add Integration"
-   - Search for "WLED Screen Controller"
-   - Enter your server URL (e.g., `http://192.168.1.100:8080`)
-   - Click Submit
-
-### Option 2: Manual Installation
-
-1. **Download Integration:**
-   ```bash
-   cd /config  # Your Home Assistant config directory
-   mkdir -p custom_components
-   ```
-
-2. **Copy Files:**
-   Copy the `custom_components/wled_screen_controller` folder to your Home Assistant `custom_components` directory.
-
-3. **Restart Home Assistant**
-
-4. **Configure Integration:**
-   - Go to Settings → Devices & Services
-   - Click "+ Add Integration"
-   - Search for "WLED Screen Controller"
-   - Enter your server URL
-   - Click Submit
-
---
-
-## Quick Start
-
-### 1. Start the Server
-
-```bash
-cd wled-screen-controller/server
-docker-compose up -d
-```
-
-### 2. Attach Your WLED Device
-
-```bash
-curl -X POST http://localhost:8080/api/v1/devices \
-  -H "Content-Type: application/json" \
-  -d '{
-    "name": "Living Room TV",
-    "url": "http://192.168.1.100",
-    "led_count": 150
-  }'
-```
-
-### 3. Configure in Home Assistant
-
-1. Add the integration (see above)
-2. Your WLED devices will appear automatically
-3. Use the switch to turn processing on/off
-4. Use the select to choose display
-5. Monitor FPS and status via sensors
-
-### 4. Start Processing
-
-Either via API:
-```bash
-curl -X POST http://localhost:8080/api/v1/devices/{device_id}/start
-```
-
-Or via Home Assistant:
- Turn on the "{Device Name} Processing" switch
-
-### 5. Enjoy Ambient Lighting!
-
-Your WLED strip should now sync with your screen content!
-
---
-
-## Troubleshooting
-
-### Server Won't Start
-
-**Check Python version:**
-```bash
-python --version  # Should be 3.11+
-```
-
-**Check dependencies:**
-```bash
-pip list | grep fastapi
-```
-
-**Check logs:**
-```bash
-# Docker
-docker-compose logs -f
-
-# Python
-tail -f logs/wled_controller.log
-```
-
-### Home Assistant Integration Not Appearing
-
-1. Check HACS installation
-2. Clear browser cache
-3. Restart Home Assistant
-4. Check Home Assistant logs:
-   - Settings → System → Logs
-   - Search for "wled_screen_controller"
-
-### Can't Connect to Server from Home Assistant
-
-1. Verify server is running:
-   ```bash
-   curl http://YOUR_SERVER_IP:8080/health
-   ```
-
-2. Check firewall rules
-3. Ensure Home Assistant can reach server IP
-4. Try http:// not https://
-
-### WLED Device Not Responding
-
-1. Check WLED device is powered on
-2. Verify IP address is correct
-3. Test WLED directly:
-   ```bash
-   curl http://YOUR_WLED_IP/json/info
-   ```
-
-4. Check network connectivity
-
-### Low FPS / Performance Issues
-
-1. Reduce target FPS (Settings → Devices)
-2. Reduce `border_width` in settings
-3. Check CPU usage on server
-4. Consider reducing LED count
-
---
-
-## Configuration Examples
-
-### Server Environment Variables
-
-```bash
-# Docker .env file
-WLED_SERVER__HOST=0.0.0.0
-WLED_SERVER__PORT=8080
-WLED_SERVER__LOG_LEVEL=INFO
-WLED_PROCESSING__DEFAULT_FPS=30
-WLED_PROCESSING__BORDER_WIDTH=10
-```
-
-### Home Assistant Automation Example
+### Automation example

 ```yaml
 automation:
-  - alias: "Auto Start WLED on TV On"
+  - alias: "Start ambient lighting when TV turns on"
    trigger:
      - platform: state
        entity_id: media_player.living_room_tv
@@ -285,7 +226,7 @@ automation:
        target:
          entity_id: switch.living_room_tv_processing

-  - alias: "Auto Stop WLED on TV Off"
+  - alias: "Stop ambient lighting when TV turns off"
    trigger:
      - platform: state
        entity_id: media_player.living_room_tv
@@ -298,8 +239,89 @@ automation:

 ---

+## Configuration Reference
+
+The server reads configuration from three sources (in order of priority):
+
+1. **Environment variables** -- prefix `WLED_`, double underscore as nesting delimiter (e.g., `WLED_SERVER__PORT=9090`)
+2. **YAML config file** -- `server/config/default_config.yaml` (or set `WLED_CONFIG_PATH` to override)
+3. **Built-in defaults**
+
+See [`server/.env.example`](server/.env.example) for every available variable with descriptions.
+
+### Key settings
+
+| Variable | Default | Description |
+| -------- | ------- | ----------- |
+| `WLED_SERVER__PORT` | `8080` | HTTP listen port |
+| `WLED_SERVER__LOG_LEVEL` | `INFO` | `DEBUG`, `INFO`, `WARNING`, `ERROR` |
+| `WLED_SERVER__CORS_ORIGINS` | `["http://localhost:8080"]` | Allowed CORS origins (JSON array) |
+| `WLED_AUTH__API_KEYS` | `{"dev":"development-key..."}` | API keys (JSON object) |
+| `WLED_MQTT__ENABLED` | `false` | Enable MQTT for HA auto-discovery |
+| `WLED_MQTT__BROKER_HOST` | `localhost` | MQTT broker address |
+| `WLED_DEMO` | `false` | Enable demo mode (sandbox with virtual devices) |
+
+---
+
+## Troubleshooting
+
+### Server will not start
+
+**Check Python version:**
+
+```bash
+python --version  # must be 3.11+
+```
+
+**Check the frontend bundle exists:**
+
+```bash
+ls server/src/wled_controller/static/dist/app.bundle.js
+```
+
+If missing, run `cd server && npm ci && npm run build`.
+
+**Check logs:**
+
+```bash
+# Docker
+docker compose logs -f
+
+# Manual install
+tail -f logs/wled_controller.log
+```
+
+### Cannot access the dashboard from another machine
+
+1. Verify the server is reachable: `curl http://SERVER_IP:8080/health`
+2. Check your firewall allows inbound traffic on port 8080.
+3. Add your server's LAN IP to `cors_origins` (see [Configure CORS](#configure-cors-for-lan-access) above).
+
+### Home Assistant integration not appearing
+
+1. Verify HACS installed the component: check that `config/custom_components/wled_screen_controller/` exists.
+2. Clear your browser cache.
+3. Restart Home Assistant.
+4. Check logs at **Settings > System > Logs** and search for `wled_screen_controller`.
+
+### WLED device not responding
+
+1. Confirm the device is powered on and connected to Wi-Fi.
+2. Test it directly: `curl http://DEVICE_IP/json/info`
+3. Check that the server and the device are on the same subnet.
+4. Try restarting the WLED device.
+
+### Low FPS or high latency
+
+1. Lower the target FPS in the stream settings.
+2. Reduce `border_width` to decrease the number of sampled pixels.
+3. Check CPU usage on the server (`htop` or Task Manager).
+4. On Windows, install the `perf` extra for GPU-accelerated capture: `pip install ".[perf]"`
+
+---
+
 ## Next Steps

 - [API Documentation](docs/API.md)
 - [Calibration Guide](docs/CALIBRATION.md)
- [GitHub Issues](https://github.com/yourusername/wled-screen-controller/issues)
+- [Repository Issues](https://git.dolgolyov-family.by/alexei.dolgolyov/wled-screen-controller-mixed/issues)