Added sway support and created initial xp overlay with gtk-layer-shell

2025-06-15 01:31:43 -06:00
parent d34cccc253
commit 4c07690e85
151 changed files with 7290 additions and 247 deletions
@@ -2,75 +2,277 @@

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

+## Project Overview
+
+XP Nix is a productivity tracking and gamification system designed for Linux desktop environments, supporting both
+Hyprland and Sway window managers. It transforms daily computer usage into a gamified experience by monitoring
+activity patterns and providing real-time feedback through an XP (experience points) system.
+
+### Window Manager Support
+
+**Hyprland**: Full feature support including visual desktop enhancements, idle monitoring, and activity detection
+**Sway**: Core functionality with idle monitoring and activity detection (visual enhancements disabled by design)
+**Detection**: Automatic runtime detection via environment variables (`HYPRLAND_INSTANCE_SIGNATURE`, `SWAYSOCK`)
+
 ## Commands

 ### Development
- `dart run bin/xp_nix.dart` - Run the main application
- `dart test` - Run all tests  
+- `dart run bin/xp_nix.dart` - Run the main application server
+- `dart run bin/xp_nix.dart --help` - Show command line options
+- `dart run bin/xp_nix.dart --db custom.db --port 8081` - Run with custom database and port
+- `dart test` - Run all tests
 - `dart test test/specific_test.dart` - Run a specific test file
- `dart analyze` - Run static analysis
+- `dart analyze` - Run static analysis and linting
 - `dart pub get` - Install dependencies
- `nix develop` - Enter development environment with Dart and SQLite
+
+### Interactive Commands (while running)
+Once the server is running, these commands are available in the terminal:
+- `stats` - Show current productivity stats
+- `test [level]` - Test theme for specific level
+- `restore` - Restore desktop backup
+- `refresh` - Refresh base config from current system config  
+- `build` - Build Flutter dashboard and copy to static files
+- `help` - Show available commands

 ### Nix Environment
-This project uses Nix flakes for development environment management. The flake provides Dart SDK and SQLite with proper library paths configured.
+This project uses Nix flakes for development environment management. The flake provides Dart SDK and SQLite with proper library paths configured:
+- `nix develop` - Enter development environment with Dart and SQLite

 ## Architecture Overview

-### Dependency Injection & Testing
-The codebase uses dependency injection through interfaces to enable both production and testing modes:
-
- **Interfaces** (`lib/src/interfaces/`): Define contracts for core components
-  - `IActivityDetector` - Window/application activity detection
-  - `IIdleMonitor` - User idle state monitoring  
-  - `IDesktopEnhancer` - Desktop theme/visual enhancements
-  - `ITimeProvider` - Time operations (for testing time manipulation)
-
- **Production Implementations**: Real system integrations (Hyprland, system time)
- **Test Mocks** (`lib/src/testing/`): Controllable implementations for testing
-
 ### Core Components

-**ProductivityMonitor** - Central orchestrator that:
+**ProductivityMonitor** (`lib/src/monitors/productivity_monitor.dart`) - Central orchestrator that:
 - Coordinates activity detection, idle monitoring, and desktop enhancement
 - Calculates XP rewards based on activity types and time multipliers
 - Manages level progression and achievement system
- Handles both event-driven (via IActivityDetector) and polling modes
+- Supports both event-driven (via IActivityDetector) and legacy polling modes
+- Broadcasts updates via WebSocket for real-time dashboard updates

-**Activity Classification System**:
- Uses `ActivityEventType` enum for categorizing activities (coding, meetings, etc.)
- Supports user-defined application classifications stored in database
- Fallback categorization based on application names and window titles
+**DashboardServer** (`lib/src/web/dashboard_server.dart`) - Web server providing:
+- RESTful API endpoints for stats, achievements, activities, and configuration
+- Real-time WebSocket connections for live updates
+- Serves Flutter-built dashboard from static files
+- Configurable port (default: 8080)

-**XP & Gamification**:
- Time-based multipliers for deep work hours vs late night penalty
- Focus session bonuses with milestone rewards (60min, 120min, 180min)
- Level-based visual themes applied via desktop enhancer
- Achievement system with level, focus, and session-based rewards
-
-### Database Schema
-SQLite database with tables for:
- Daily stats (XP, focus time, meeting time, level)
+**DatabaseManager** (`lib/src/database/database_manager.dart`) - SQLite database operations for:
+- Daily stats tracking (XP, focus time, meeting time, level)
 - Activity events with duration and metadata
 - Application classifications (user-defined)
 - Achievements and focus sessions
 - Theme change history and streak tracking

-### Configuration
-JSON-based configuration (`config/xp_config.json`) defines:
- XP multipliers by activity type and time of day
- Achievement definitions and rewards
- Focus session bonus structure
- Monitoring intervals and thresholds
+### Dependency Injection & Testing

-### Web Dashboard
-Built-in web server (`lib/src/web/`) provides real-time dashboard at http://localhost:8080 showing stats, recent activities, and progress visualization.
+The codebase uses dependency injection through interfaces to enable both production and testing modes:
+
+**Interfaces** (`lib/src/interfaces/`):
+- `IActivityDetector` - Window/application activity detection
+- `IIdleMonitor` - User idle state monitoring  
+- `IDesktopEnhancer` - Desktop theme/visual enhancements
+- `ITimeProvider` - Time operations (for testing time manipulation)
+- `IWindowManager` - Window manager operations abstraction
+
+**Hyprland Implementations**:
+- `HyprlandActivityDetector` - Uses `hyprctl activewindow` for activity detection
+- `IdleMonitor` - Uses `hypridle` for idle state monitoring
+- `HyprlandEnhancer` - Full desktop theming and visual enhancements
+- `HyprlandManager` - Window manager operations via `hyprctl`
+
+**Sway Implementations**:
+- `SwayActivityDetector` - Uses `swaymsg -t get_tree` for activity detection
+- `SwayIdleMonitor` - Uses `swayidle` for idle state monitoring
+- `SwayEnhancer` - Notifications-only enhancer (no visual changes)
+- `SwayManager` - Window manager operations via `swaymsg`
+
+**Factory Classes** (`lib/src/factories/`):
+- `IdleMonitorFactory` - Creates appropriate idle monitor for detected window manager
+- `ActivityDetectorFactory` - Creates appropriate activity detector for detected window manager
+- `DesktopEnhancerFactory` - Creates appropriate enhancer for detected window manager
+- `WindowManagerFactory` - Creates appropriate window manager interface
+
+**Test Mocks** (`lib/src/testing/`):
+- `MockActivityDetector` - Controllable activity simulation
+- `MockIdleMonitor` - Controllable idle state simulation
+- `MockDesktopEnhancer` - No-op desktop enhancement for testing
+- `MockTimeProvider` - Controllable time for testing
+- `MockWindowManagerDetector` - Test scenarios for different window managers
+
+### Activity Classification System
+
+**ActivityEventType** enum categorizes activities:
+- `coding` - Development work (10 XP/min base)
+- `focusedBrowsing` - Research and documentation (6 XP/min base)
+- `collaboration` - Team communication (7 XP/min base)
+- `meetings` - Video conferences and calls (3 XP/min base)
+- `misc` - General productivity (2 XP/min base)
+- `uncategorized` - Unknown activities (1 XP/min base)
+
+**Classification Logic**:
+- Uses user-defined application classifications stored in database
+- Fallback categorization based on application names and window titles
+- Tracks unclassified applications for manual categorization
+
+### XP & Gamification System
+
+**XP Calculation**:
+- Base XP per minute varies by activity type
+- Time-based multipliers from configuration:
+  - Deep work hours (1.5x): 09:00-11:00, 14:00-16:00
+  - Late night penalty (0.8x): 22:00-06:00
+- Focus session bonuses: 60min (+100 XP), 120min (+200 XP), 180min (+500 XP)
+
+**Level System**:
+- 100 XP per level progression
+- Visual desktop themes applied at different levels
+- Achievement system with level, focus, and session-based rewards
+
+**Achievements**:
+- Level-based: Rising Star (L5), Productivity Warrior (L10), Focus Master (L15), Legendary Achiever (L25)
+- Focus-based: Deep Focus (4h), Focus Titan (8h)
+- Session-based: Session Master (5+ sessions)
+- Meeting-based: Communication Pro (3h meetings)
+
+### Configuration Management
+
+**ConfigManager** (`lib/src/config/config_manager.dart`):
+- Loads from `config/xp_config.json`
+- Manages XP multipliers, achievement definitions, focus bonuses
+- Supports runtime configuration updates via web API
+
+**Key Configuration Sections**:
+- `xp_rewards` - Base multipliers and time-based modifiers
+- `achievements` - Achievement definitions and rewards
+- `level_system` - XP per level and max level
+- `monitoring` - Polling intervals and thresholds
+- `logging` - Log levels and file management
+
+### Web Dashboard & API
+
+**Dashboard Features**:
+- Real-time stats display with WebSocket updates
+- Activity timeline and XP breakdown charts
+- Achievement gallery and progress tracking
+- Application classification management
+- Configuration editor
+- Log viewer with filtering
+
+**API Endpoints**:
+- `GET /api/stats` - Current day statistics
+- `GET /api/stats/history?days=7` - Historical stats
+- `GET /api/achievements` - All achievements
+- `GET /api/activities?limit=100` - Recent activities
+- `GET /api/focus-sessions` - Focus session history
+- `GET /api/xp-breakdown` - XP breakdown by activity type
+- `GET /api/classifications` - Application classifications
+- `POST /api/classifications` - Save application classification
+- `GET /api/config` - Current configuration
+- `POST /api/config` - Update configuration
+
+**WebSocket Events**:
+- `level_up` - Level progression notifications
+- `achievement_unlocked` - Achievement notifications
+- `stats_update` - Real-time stats updates
+- `xp_breakdown_update` - XP distribution updates
+- `focus_session_complete` - Focus session completions
+
+### Flutter Dashboard Build System
+
+**DashboardBuilder** (`lib/src/build/dashboard_builder.dart`):
+- Builds Flutter dashboard from `../xp_dashboard` directory
+- Copies built web files to `lib/src/web/static/`
+- Accessible via `build` command while server is running
+- Requires Flutter to be available in system PATH

 ## Testing Strategy

-The architecture supports comprehensive testing through:
- Interface-based dependency injection
- Time manipulation via `ITimeProvider`
- Mock implementations that simulate user behavior
- Simulation tests that model complete work days
- Integration tests for idle detection and activity consolidation
+### Test Structure
+- **Unit Tests**: Individual component testing with mocks
+- **Integration Tests**: WebSocket and database integration
+- **Simulation Tests**: Complete work day scenarios
+- **Configuration Tests**: Hyprland config parsing
+
+### Key Test Files
+- `test/xp_nix_test.dart` - Main productivity monitor tests
+- `test/websocket_integration_test.dart` - WebSocket functionality
+- `test/simulation/` - Work day simulation scenarios
+- `test/deep_idle_test.dart` - Idle detection edge cases
+- `test/hyprland_config_parser_test.dart` - Configuration parsing
+- `test/sway_integration_test.dart` - Sway window manager integration tests
+
+### Testing Utilities
+- `test/create_golden_db.dart` - Creates test database with sample data
+- Time manipulation via `MockTimeProvider` for deterministic testing
+- Activity simulation via `MockActivityDetector` for scenario testing
+
+## System Requirements & Compatibility
+
+### Window Manager Requirements
+
+**Hyprland Environment**:
+- `hyprctl` - Window management and querying
+- `hypridle` - Idle detection and monitoring
+- Environment: `$HYPRLAND_INSTANCE_SIGNATURE` must be set
+
+**Sway Environment**:
+- `swaymsg` - Window management and querying  
+- `swayidle` - Idle detection and monitoring
+- Environment: `$SWAYSOCK` must be set
+
+**Optional Dependencies**:
+- `notify-send` - Desktop notifications (both window managers)
+- `mako` or `dunst` - Enhanced notification daemons (Sway)
+
+### Feature Comparison
+
+| Feature | Hyprland | Sway | Notes |
+|---------|----------|------|-------|
+| Activity Detection | ✅ | ✅ | Uses `hyprctl` vs `swaymsg` |
+| Idle Monitoring | ✅ | ✅ | Uses `hypridle` vs `swayidle` |
+| Visual Enhancements | ✅ | ❌ | Disabled by design for Sway |
+| Desktop Theming | ✅ | ❌ | Config modifications disabled |
+| Notifications | ✅ | ✅ | Level-up and achievement alerts |
+| WebSocket API | ✅ | ✅ | Full dashboard functionality |
+| Database Tracking | ✅ | ✅ | Identical functionality |
+
+### Runtime Detection
+
+The system automatically detects your window manager at startup:
+
+1. **Environment Variables**: Checks `$HYPRLAND_INSTANCE_SIGNATURE` and `$SWAYSOCK`
+2. **Process Detection**: Falls back to checking available commands
+3. **Graceful Degradation**: Uses appropriate implementations or fallbacks
+
+## Development Workflow
+
+### Initial Setup
+1. `dart pub get` - Install dependencies
+2. `dart run bin/xp_nix.dart` - Start server (auto-detects window manager)
+3. Visit `http://localhost:8080` for dashboard
+
+### Making Changes
+1. Run tests: `dart test`
+2. Check analysis: `dart analyze`
+3. Test with custom database: `dart run bin/xp_nix.dart --db test.db`
+4. Build dashboard: Use `build` command at runtime command `flutter build web` in `../xp_dashboard`
+
+### Configuration Changes
+- Edit `config/xp_config.json` for XP rules and achievements
+- Use `refresh` command to reload configuration
+- Test theme changes with `test [level]` command
+- Use `restore` command if desktop theme issues occur
+
+## Roadmap Integration
+
+The project roadmap includes ambitious enhancements:
+- **Cursor-following XP numbers** - RPG-style floating damage numbers
+- **Dual currency shop system** - XP points and real-world reward tokens
+- **Enhanced celebrations** - Full-screen level-up animations
+- **Environmental feedback** - Focus-based ambient changes
+- **Real-world purchase integration** - Automated reward fulfillment
+
+Current architecture supports these extensions through:
+- Modular desktop enhancement system
+- Extensible notification framework
+- Configurable reward and achievement system
+- Database schema designed for expansion