Major vibe-refactor

[zulufoxtrot]

Hi Richard. Sorry for the entirely AI-generated PR description, but I think it should describe the changes accuratedly.

In a nutshell:

• reorganized, rewrote in part, simplified to make it easier to contribute to in the future
• added unit tests (useful to prevent regressions when changing code)
• added documentation
• uses default value for serial number for ME3000SP

No behavior change expected.

I tested it on my ME3000SP:

• serial works
• mqtt works
• reading works
• writing (inverter mode change) works

Could you try testing on your own inverter? Thanks!

---

PR Summary: Major Refactor - Modular Architecture with Comprehensive Testing

Overall Impact

This PR represents a complete architectural refactor of the sofar2mqtt codebase, transforming it from a monolithic single-file script (sofar2mqtt-v2.py) into a well-structured, production-ready Python package with proper modularity, type safety, and test coverage.

---

Structural Changes

Aspect	Before	After
Project Structure	Single 1200+ line script (sofar2mqtt-v2.py)	Modular package with clear separation of concerns
Configuration	Ad-hoc JSON loading in main class	Dedicated config/loader.py with Pydantic validation
Modbus Communication	Direct minimalmodbus calls scattered throughout	Dedicated core/modbus_client.py with thread-safe wrapper
MQTT Layer	Inline paho-mqtt code	Clean mqtt/client.py and mqtt/discovery.py
Value Transformations	Inline conversion logic	Reusable transformations/converter.py
Entry Point	Direct script execution	Click CLI with cli.py and proper package entry points

---

Key Improvements

1. Modular Architecture (6 core modules)

   • sofar2mqtt/models/ - Pydantic data models (RegisterDefinition, InverterConfig)
   • sofar2mqtt/core/ - Business logic (ModbusClient, SofarClient)
   • sofar2mqtt/mqtt/ - MQTT client and HA discovery
   • sofar2mqtt/config/ - Configuration loading and validation
   • sofar2mqtt/transformations/ - Value conversion utilities
   • sofar2mqtt/utils/ - Cross-cutting concerns (retry, logging)

2. Type Safety - Pydantic v2 models for all data structures with validation

3. Dependency Injection - Components passed to SofarClient rather than created internally, enabling easy testing

4. CLI with Click - Full argument parsing with environment variable support and help text

5. Modern Tooling

   • pyproject.toml with proper package metadata and dev dependencies
   • ruff.toml for linting/formatting configuration
   • CI workflow (tests.yml) with coverage reporting

---

Test Coverage (75 Tests, 64% Code Coverage)

New Tests Added:

Test File	Coverage
tests/test_modbus.py	133 lines - Modbus client setup, read/write operations
tests/test_mqtt.py	99 lines - MQTT client and HA discovery
tests/test_sofar_client.py	374 lines - Full orchestrator lifecycle and state management
tests/test_transformations.py	241 lines - All value conversion functions

Test Scenarios Covered:

• Modbus client initialization and configuration
• Register read/write operations (success and failure cases)
• HA discovery message generation
• State updates with refresh interval filtering
• MQTT callbacks (connect, message handling)
• Value transformations (multiply/divide/mode/bit_field/high_low_bit)
• Aggregate register calculations (add/subtract/avg)
• Write register handling with special mode constraints
• Graceful shutdown and cleanup

---

Testing on ME3000SP

The refactor maintains full compatibility with existing configurations (config files unchanged) while adding the ability to automatically detect device type and load appropriate configuration.

---

Breaking Changes / Notes

• sofar2mqtt-v2.py removed (replaced by sofar2mqtt/ package)
• CLI usage changed from python sofar2mqtt-v2.py ... to sofar2mqtt ...
• Package is now installable via pip with proper entry point