Modular architecture with abstract targets and enhanced ICS support

[PortableProgrammer]

Modular Architecture with Abstract Targets and Enhanced ICS Support

This release introduces significant architectural improvements and new features while maintaining backward compatibility.

Major Changes

1. Modular Status Precedence Logic

Issue: Hardcoded 35-line if/elif chain for status selection made it difficult to add new sources or test precedence rules.

Solution: Extracted precedence logic into new utility/precedence.py module with dictionary-based approach.

Benefits:

• ✅ Cleaner, more testable code
• ✅ Enhanced debug logging shows decision flow
• ✅ Easy to add new status sources
• ✅ Reduced main code complexity

Details:

• New precedence.select_status() function with comprehensive logging
• Logs collaboration sources, calendar sources, and final selection
• Returns tuple of (Status, StatusSource) for better traceability

2. Abstract Light Target Interface

Issue: Main codebase contained Tuya-specific dependencies (TuyaMode, device-specific brightness scale, set_status signature).

Solution: Created abstract LightTarget base class with simple, device-agnostic interface.

Benefits:

• ✅ Easy to add new light targets (Hue, LIFX, HomeKit, etc.)
• ✅ Main code has zero device-specific knowledge
• ✅ Tuya locked to COLOR mode (simpler, more consistent)
• ✅ Clean separation of concerns

Interface:

class LightTarget(ABC):
    def set_color(self, color: str, brightness: int) -> bool
    def turn_off(self) -> bool
    def validate_color(self, color: str) -> bool
    def validate_brightness(self, brightness: int) -> bool

Implementations:

• targets/base.py - Abstract interface definition
• targets/tuya.py - Tuya implementation (locked to COLOR mode, converts percentage to 0-255)
• targets/virtual.py - Virtual implementation (simplified, removed mode tracking)

3. Percentage-Based Brightness

Issue: Brightness used Tuya's device-specific 0-255 scale, not intuitive for users or portable across devices.

Solution: Changed to percentage (0-100) with automatic legacy format detection.

Benefits:

• ✅ More intuitive user experience (0-100%)
• ✅ Device-agnostic (each target converts to native scale)
• ✅ Backward compatible (auto-detects legacy 0-255 format)
• ✅ Better abstraction

Migration:

• Values > 100 auto-detected as legacy format and converted
• Default changed: 128 (0-255) → 50 (percentage), same brightness
• Informative logging when legacy format detected
• TUYA_BRIGHTNESS still supported as deprecated alias

Environment Variables:

• LIGHT_BRIGHTNESS - New percentage-based setting (0-100, default: 50)
• TUYA_BRIGHTNESS - Deprecated alias, still works

4. Enhanced ICS Calendar Support

Issue: ICS source only supported basic RFC 5545 properties, missing Office 365/Outlook's granular status information.

Solution: Added Microsoft CDO extension support for enhanced status detection.

Benefits:

• ✅ Better Office 365/Outlook ICS compatibility
• ✅ Distinguishes "away" (OOF) from "working elsewhere"
• ✅ More accurate status for remote/hybrid work
• ✅ Falls back to RFC 5545 for non-Microsoft calendars

New Status Mappings:

• X-MICROSOFT-CDO-BUSYSTATUS=OOF → OUTOFOFFICE (away/out of office)
• X-MICROSOFT-CDO-BUSYSTATUS=WORKINGELSEWHERE → WORKINGELSEWHERE (remote work)
• X-MICROSOFT-CDO-BUSYSTATUS=FREE → FREE
• X-MICROSOFT-CDO-BUSYSTATUS=TENTATIVE → TENTATIVE
• X-MICROSOFT-CDO-BUSYSTATUS=BUSY → BUSY

Updated Precedence:

• Old: BUSY > TENTATIVE > FREE
• New: BUSY > OUTOFOFFICE > WORKINGELSEWHERE > TENTATIVE > FREE

5. Enhanced Logging

Precedence Module:

• Logs input sources (collaboration and calendar)
• Logs each decision point in precedence algorithm
• Logs final selection with winning source
• All at DEBUG level for troubleshooting

ICS Source:

• Logs CDO busystatus detection and mapping
• Shows which status property was used (standard vs CDO)

Documentation Updates

• ✅ README.md - ICS CDO extensions, percentage brightness, legacy auto-detection
• ✅ CLAUDE.md - Architecture updates, precedence module, abstract targets
• ✅ All copyright years updated to 2026

Breaking Changes

None for existing users!

• Brightness auto-detection handles legacy 0-255 format
• TUYA_BRIGHTNESS still works (deprecated)
• All existing configurations work without modification

Edge Cases:

• Brightness values 0-31: Treated as percentage (unlikely user scenario)
• Lazy Tuya initialization: Connection happens on first use instead of startup (same end result, faster startup)

Migration Guide

No action required - existing configurations work as-is:

• TUYA_BRIGHTNESS=128 → Auto-converts to 50%
• TUYA_BRIGHTNESS=255 → Auto-converts to 100%
• Not set → Defaults to 50%

Recommended updates:

• Change TUYA_BRIGHTNESS → LIGHT_BRIGHTNESS (0-100 percentage)
• Example: LIGHT_BRIGHTNESS=50 (same as old TUYA_BRIGHTNESS=128)

Testing Performed

✅ Docker build succeeds (multi-platform)
✅ Python syntax validation
✅ Code linting (line length, style)
✅ ICS with Office 365 calendar (OOF events tested)
✅ Virtual target (logging verified)
✅ Tuya target (shutdown sequence verified)
✅ Brightness auto-detection (default and legacy values)
✅ Signal handling (clean shutdown)

Files Changed

New Files:

• status-light/targets/base.py (79 lines) - Abstract LightTarget interface
• status-light/utility/precedence.py (144 lines) - Status precedence module

Modified Files:

• status-light/status-light.py - Uses abstract interface, precedence module
• status-light/targets/tuya.py - Implements LightTarget, percentage conversion
• status-light/targets/virtual.py - Implements LightTarget, simplified
• status-light/sources/calendar/ics.py - CDO extension support
• status-light/utility/env.py - Percentage brightness with auto-detection
• CLAUDE.md - Architecture documentation updates
• README.md - User-facing documentation updates
• Multiple files - Copyright year updates (2026)

Statistics:

• 2 commits
• 14 files changed
• +470 insertions, -144 deletions

Future Enhancements Enabled

This release makes it easy to:

• Add new light targets (Philips Hue, LIFX, HomeKit, etc.) - just implement 2 methods
• Add new status sources - precedence module handles them automatically
• Support additional calendar formats - ICS architecture is extensible

Related Issues

Closes #74 (Log enums as names, not values)
Addresses TODO in status-light.py line 237 (build real precedence module)

---

Release Checklist:

• All tests passing
• Documentation updated
• Breaking changes documented (none)
• Migration guide provided
• Backward compatibility verified

Co-Authored-By: Claude Sonnet 4.5 noreply@anthropic.com