alexei.dolgolyov/wled-screen-controller-mixed

Files

Lint & Test / test (push) Failing after 48s

Details

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

2.8 KiB

Raw Blame History

Claude Instructions for WLED Screen Controller Server

Project Structure

src/wled_controller/main.py — FastAPI application entry point
src/wled_controller/api/routes/ — REST API endpoints (one file per entity)
src/wled_controller/api/schemas/ — Pydantic request/response models (one file per entity)
src/wled_controller/core/ — Core business logic (capture, devices, audio, processing, automations)
src/wled_controller/storage/ — Data models (dataclasses) and JSON persistence stores
src/wled_controller/utils/ — Utility functions (logging, monitor detection)
src/wled_controller/static/ — Frontend files (TypeScript, CSS, locales)
src/wled_controller/templates/ — Jinja2 HTML templates
config/ — Configuration files (YAML)
data/ — Runtime data (JSON stores, persisted state)

Entity & Storage Pattern

Each entity follows: dataclass model (storage/) + JSON store (storage/*_store.py) + Pydantic schemas (api/schemas/) + routes (api/routes/).

Authentication

Server uses API key authentication via Bearer token in Authorization header.

Config: config/default_config.yaml under auth.api_keys
Env var: WLED_AUTH__API_KEYS
Dev key: development-key-change-in-production

Common Tasks

Adding a new API endpoint

Create route file in api/routes/
Define request/response schemas in api/schemas/
Register the router in main.py
Restart the server
Test via /docs (Swagger UI)

Adding a new field to existing API

Update Pydantic schema in api/schemas/
Update corresponding dataclass in storage/
Update backend logic to populate the field
Restart the server
Update frontend to display the new field
Rebuild bundle: cd server && npm run build

Adding translations

Add keys to static/locales/en.json, static/locales/ru.json, and static/locales/zh.json
Add data-i18n attributes to HTML elements in templates/
Use t('key') in TypeScript modules (static/js/)
No server restart needed (frontend only), but rebuild bundle if JS changed

Modifying display/monitor detection

Update functions in utils/monitor_names.py or core/screen_capture.py
Restart the server
Test with GET /api/v1/config/displays

Testing

cd server && pytest                    # Run all tests
cd server && pytest --cov              # With coverage report
cd server && pytest tests/test_api.py  # Single test file

Tests are in server/tests/. Config in pyproject.toml under [tool.pytest].

Frontend Conventions

For all frontend conventions (CSS variables, UI patterns, modals, localization, icons, bundling), see contexts/frontend.md.

Server Operations

For restart procedures, server modes, and demo mode checklist, see contexts/server-operations.md.

2.8 KiB Raw Blame History