Add status script and improve installer for thesis tracker

Co-authored-by: kuhyx <147418882+kuhyx@users.noreply.github.com>
2026-07-04 14:43:08 +02:00 · 2026-01-12 21:37:32 +00:00 · 2026-01-12 21:37:32 +00:00 · c4cd889d28
commit c4cd889d28
parent 02efc737a3
3 changed files with 474 additions and 0 deletions
--- a/scripts/digital_wellbeing/README_THESIS_TRACKER.md
+++ b/scripts/digital_wellbeing/README_THESIS_TRACKER.md
@ -0,0 +1,314 @@
+# Bachelor Thesis Work Tracker
+
+A comprehensive system to help you stay focused on your bachelor thesis by blocking distractions until you've put in your work hours.
+
+## Overview
+
+This system monitors your active windows and tracks time spent on thesis-related work. Steam and other distracting websites are blocked until you accumulate the required work time. It's designed to be as hard to circumvent as possible while remaining fair and transparent.
+
+## How It Works
+
+1. **Work Tracking**: The system monitors your active window every 5 seconds
+2. **Time Accumulation**: When you're working on approved thesis applications, time accumulates
+3. **Unlocking**: After reaching the work quota (default: 2 hours), distractions are unblocked
+4. **Decay System**: Using Steam or distractions decays your work time (default: 30 minutes per hour)
+5. **Re-blocking**: When work time falls below quota, distractions are blocked again
+
+## Tracked Applications
+
+The following applications count as "thesis work":
+
+### Game Engines
+- **Unreal Engine** (all versions: UE4, UE5, UnrealEditor)
+- **Unity Engine** (Unity Editor and Unity Hub)
+- **Nvidia Omniverse** (Omniverse and Kit)
+
+### Development Tools
+- **Visual Studio Code** - **ONLY** when working on the `praca_magisterska` repository
+  - The window title must contain the repository name
+  - Or the workspace must have the repository open
+
+## Blocked Sites
+
+When you haven't met your work quota, the following are blocked via `/etc/hosts`:
+
+### Gaming
+- All Steam domains (steampowered.com, steamcommunity.com, etc.)
+
+### Social Media
+- Reddit
+- Twitter/X
+- Facebook
+- Instagram
+
+### Video/Entertainment
+- YouTube
+- Twitch
+- 9gag
+- Imgur
+
+## Installation
+
+### Quick Start
+
+```bash
+# Clone or navigate to the repository
+cd /path/to/scripts
+
+# Run the installer (will prompt for sudo)
+sudo scripts/digital_wellbeing/setup_thesis_work_tracker.sh
+```
+
+### Custom Configuration
+
+```bash
+# Set custom work quota (e.g., 3 hours)
+sudo scripts/digital_wellbeing/setup_thesis_work_tracker.sh --work-quota 180
+
+# Set custom decay rate (e.g., 20 minutes per hour)
+sudo scripts/digital_wellbeing/setup_thesis_work_tracker.sh --decay-rate 20
+
+# Set custom VS Code repository name
+sudo scripts/digital_wellbeing/setup_thesis_work_tracker.sh --vscode-repo "my-thesis-repo"
+
+# Combine multiple options
+sudo scripts/digital_wellbeing/setup_thesis_work_tracker.sh \
+    --work-quota 150 \
+    --decay-rate 25 \
+    --vscode-repo "bachelor-thesis"
+```
+
+### Prerequisites
+
+The installer will check for required dependencies:
+- `xdotool` - for window detection
+- `systemd` - for service management
+
+On Arch Linux:
+```bash
+sudo pacman -S xdotool
+```
+
+On Ubuntu/Debian:
+```bash
+sudo apt install xdotool
+```
+
+## Usage
+
+### After Installation
+
+The system runs automatically as a systemd service. Just start working on your thesis!
+
+### Checking Your Progress
+
+```bash
+# View current status
+systemctl status thesis-work-tracker@$USER.service
+
+# View live logs
+tail -f /var/log/thesis-work-tracker/tracker.log
+
+# Check your accumulated work time
+sudo cat /var/lib/thesis-work-tracker/work-time.state
+```
+
+### Understanding the State File
+
+The state file shows:
+- `TOTAL_WORK_SECONDS`: Your accumulated work time (in seconds)
+- `STEAM_ACCESS_GRANTED`: Whether distractions are currently unblocked (1=yes, 0=no)
+- `CURRENT_SESSION_SECONDS`: Time in your current work session
+- `LAST_WORK_SESSION_START`: When your current session started
+
+### Managing the Service
+
+```bash
+# Restart the service
+sudo systemctl restart thesis-work-tracker@$USER.service
+
+# Stop the service temporarily
+sudo systemctl stop thesis-work-tracker@$USER.service
+
+# Start the service
+sudo systemctl start thesis-work-tracker@$USER.service
+
+# Disable auto-start
+sudo systemctl disable thesis-work-tracker@$USER.service
+
+# Re-enable auto-start
+sudo systemctl enable thesis-work-tracker@$USER.service
+```
+
+## Uninstallation
+
+```bash
+sudo scripts/digital_wellbeing/setup_thesis_work_tracker.sh --uninstall
+```
+
+**Note**: This preserves your state file and logs. To completely remove everything:
+
+```bash
+# Remove state directory
+sudo chattr -i -R /var/lib/thesis-work-tracker
+sudo rm -rf /var/lib/thesis-work-tracker
+
+# Remove logs
+sudo rm -rf /var/log/thesis-work-tracker
+```
+
+## Security & Anti-Circumvention Features
+
+This system is designed to be difficult to bypass:
+
+### 1. **Immutable State Files**
+- State files are protected with `chattr +i` (immutable flag)
+- Cannot be edited even by root without removing the flag first
+- Automatically re-applied after each update
+
+### 2. **Auto-Restart Service**
+- Systemd service automatically restarts if killed
+- Runs continuously in the background
+- Starts automatically on boot
+
+### 3. **Hosts File Integration**
+- Integrates with the repository's hosts guard system
+- Uses immutable `/etc/hosts` file
+- Cannot be easily bypassed by changing DNS
+
+### 4. **Process Integrity**
+- Monitors actual active windows, not just running processes
+- Detects if you switch away from work applications
+- VS Code requires specific repository to be open
+
+### 5. **Decay Mechanism**
+- Using Steam/distractions consumes your earned work time
+- Forces sustained work habits, not just one-time work sessions
+- Fair: 30 minutes of decay per hour of distraction usage
+
+### 6. **Locked Configuration**
+- Configuration is embedded in the installed script
+- Cannot be easily modified without reinstalling
+- Protected script location in `/usr/local/bin`
+
+## Troubleshooting
+
+### Service Not Starting
+
+```bash
+# Check service status
+systemctl status thesis-work-tracker@$USER.service
+
+# Check for errors
+journalctl -u thesis-work-tracker@$USER.service -n 50
+
+# Verify dependencies
+which xdotool
+which systemctl
+```
+
+### Window Detection Not Working
+
+The tracker requires X11 and `xdotool`. Check:
+
+```bash
+# Verify X11 is running
+echo $DISPLAY
+
+# Test xdotool
+xdotool getactivewindow getwindowname
+
+# Check XAUTHORITY
+echo $XAUTHORITY
+ls -la ~/.Xauthority
+```
+
+### VS Code Repository Not Detected
+
+Make sure:
+1. The window title shows the repository name
+2. You're working in the correct repository folder
+3. The repository name matches what you specified during installation
+
+Test with:
+```bash
+xdotool getactivewindow getwindowname
+# Should show something like: "praca_magisterska - Visual Studio Code"
+```
+
+### Hosts File Not Updating
+
+Check:
+```bash
+# View current hosts file
+sudo cat /etc/hosts | grep steam
+
+# Check immutable flag
+lsattr /etc/hosts
+
+# Service logs
+tail -f /var/log/thesis-work-tracker/tracker.log
+```
+
+## Configuration Files
+
+- **Tracker Script**: `/usr/local/bin/thesis_work_tracker.sh`
+- **Systemd Service**: `/etc/systemd/system/thesis-work-tracker@.service`
+- **State File**: `/var/lib/thesis-work-tracker/work-time.state`
+- **Log File**: `/var/log/thesis-work-tracker/tracker.log`
+
+## Tips for Success
+
+1. **Start Early**: Begin your work sessions in the morning when you're fresh
+2. **Take Breaks**: The system only tracks active window time, so take regular breaks
+3. **Focus Sessions**: Work in focused 2-hour blocks to unlock entertainment
+4. **Monitor Progress**: Check your logs regularly to see your work patterns
+5. **Be Honest**: The system trusts you're actually working when applications are open
+
+## FAQ
+
+### Can I bypass this system?
+
+Technically yes, but it's designed to make bypassing more effort than just doing the work:
+- You'd need to disable the service (but it auto-restarts)
+- You'd need to modify immutable files (requires chattr commands)
+- You'd need to fake window activity (complex)
+- You'd need to edit protected state files (also complex)
+
+The point isn't to make it impossible, but to add enough friction that doing your thesis work is easier.
+
+### What if I need to use VS Code for something else?
+
+VS Code only counts as work when you're in the `praca_magisterska` repository. Other projects won't count toward your thesis time.
+
+### Can I adjust the work quota after installation?
+
+Yes, but you need to:
+1. Uninstall the current system
+2. Reinstall with new parameters
+3. Your accumulated time is preserved in the state file
+
+### Does this work on Wayland?
+
+Currently, this requires X11 for `xdotool` window detection. Wayland support would require adapting to use different tools like `wlrctl` or `swaymsg`.
+
+### What happens if I reboot?
+
+The service starts automatically on boot, and your accumulated work time is preserved in the state file.
+
+## License
+
+This is part of the kuhyx/scripts repository. Use at your own risk and discretion.
+
+## Contributing
+
+Found a bug or have a suggestion? Please open an issue in the main repository.
+
+## Acknowledgments
+
+This tool is built on top of the digital wellbeing framework in this repository, including:
+- Hosts guard system
+- Psychological friction mechanisms  
+- Systemd service patterns
+
+Good luck with your bachelor thesis! 🎓
--- a/scripts/digital_wellbeing/setup_thesis_work_tracker.sh
+++ b/scripts/digital_wellbeing/setup_thesis_work_tracker.sh
@ -45,8 +45,10 @@ UNINSTALL=0
 ######################################################################
 SCRIPT_DIR="$(dirname "$(readlink -f "$0")")"
 TRACKER_SCRIPT="$SCRIPT_DIR/thesis_work_tracker.sh"
+STATUS_SCRIPT="$SCRIPT_DIR/thesis_work_status.sh"
 SERVICE_FILE="$SCRIPT_DIR/systemd/thesis-work-tracker@.service"
 INSTALL_BIN="/usr/local/bin/thesis_work_tracker.sh"
+INSTALL_STATUS="/usr/local/bin/thesis_work_status"
 INSTALL_SERVICE="/etc/systemd/system/thesis-work-tracker@.service"
 STATE_DIR="/var/lib/thesis-work-tracker"
 LOG_DIR="/var/log/thesis-work-tracker"
@ -195,6 +197,11 @@ uninstall_tracker() {
        run rm -f "$INSTALL_BIN"
    fi
    
+    # Remove status script
+    if [[ -f $INSTALL_STATUS ]]; then
+        run rm -f "$INSTALL_STATUS"
+    fi
+    
    # Remove state directory (with immutable flags removed)
    if [[ -d $STATE_DIR ]]; then
        run chattr -i -R "$STATE_DIR" 2>/dev/null || true
@ -218,6 +225,11 @@ install_tracker() {
        exit 1
    fi
    
+    if [[ ! -f $STATUS_SCRIPT ]]; then
+        err "Status script not found: $STATUS_SCRIPT"
+        exit 1
+    fi
+    
    if [[ ! -f $SERVICE_FILE ]]; then
        err "Service file not found: $SERVICE_FILE"
        exit 1
@ -244,6 +256,15 @@ install_tracker() {
    
    run chmod 755 "$INSTALL_BIN"
    
+    # Install status script
+    msg "Installing status script to $INSTALL_STATUS..."
+    run cp "$STATUS_SCRIPT" "$INSTALL_STATUS"
+    
+    # Update quota in status script to match
+    run sed -i "s/^WORK_QUOTA_REQUIRED=.*/WORK_QUOTA_REQUIRED=$work_quota_seconds  # $WORK_QUOTA_MINUTES minutes/" "$INSTALL_STATUS"
+    
+    run chmod 755 "$INSTALL_STATUS"
+    
    # Install systemd service
    msg "Installing systemd service..."
    run cp "$SERVICE_FILE" "$INSTALL_SERVICE"
@ -307,6 +328,7 @@ install_tracker() {
    echo "  5. When work time drops below quota, Steam is blocked again"
    echo ""
    echo "Useful Commands:"
+    echo "  • Check progress: thesis_work_status"
    echo "  • Check status:   systemctl status thesis-work-tracker@$user.service"
    echo "  • View logs:      tail -f $LOG_DIR/tracker.log"
    echo "  • View state:     sudo cat $STATE_DIR/work-time.state"
--- a/scripts/digital_wellbeing/thesis_work_status.sh
+++ b/scripts/digital_wellbeing/thesis_work_status.sh
@ -0,0 +1,138 @@
+#!/bin/bash
+# Quick status checker for thesis work tracker
+# Shows current work progress and access status
+
+set -euo pipefail
+
+STATE_FILE="/var/lib/thesis-work-tracker/work-time.state"
+
+# Colors
+GREEN='\033[0;32m'
+RED='\033[0;31m'
+YELLOW='\033[0;33m'
+BLUE='\033[0;34m'
+BOLD='\033[1m'
+NC='\033[0m'
+
+# Check if state file exists
+if [[ ! -f $STATE_FILE ]]; then
+    echo -e "${RED}Error:${NC} Thesis work tracker is not installed or has not been initialized."
+    echo "Install with: sudo scripts/digital_wellbeing/setup_thesis_work_tracker.sh"
+    exit 1
+fi
+
+# Load state (need sudo to read immutable file)
+if [[ $EUID -ne 0 ]]; then
+    exec sudo -E bash "$0" "$@"
+fi
+
+# Temporarily remove immutable to read
+sudo chattr -i "$STATE_FILE" 2>/dev/null || true
+
+# Source the state file
+# shellcheck source=/dev/null
+source "$STATE_FILE" 2>/dev/null || {
+    echo -e "${RED}Error:${NC} Could not read state file"
+    exit 1
+}
+
+# Re-apply immutable
+sudo chattr +i "$STATE_FILE" 2>/dev/null || true
+
+# Default values if not set
+TOTAL_WORK_SECONDS=${TOTAL_WORK_SECONDS:-0}
+STEAM_ACCESS_GRANTED=${STEAM_ACCESS_GRANTED:-0}
+CURRENT_SESSION_SECONDS=${CURRENT_SESSION_SECONDS:-0}
+LAST_WORK_SESSION_START=${LAST_WORK_SESSION_START:-0}
+
+# Constants (should match tracker script)
+WORK_QUOTA_REQUIRED=7200  # 2 hours default
+
+# Calculate values
+work_minutes=$((TOTAL_WORK_SECONDS / 60))
+work_hours=$((work_minutes / 60))
+work_remaining_minutes=$((work_minutes % 60))
+
+quota_minutes=$((WORK_QUOTA_REQUIRED / 60))
+quota_hours=$((quota_minutes / 60))
+quota_remaining_minutes=$((quota_minutes % 60))
+
+remaining_seconds=$((WORK_QUOTA_REQUIRED - TOTAL_WORK_SECONDS))
+if [[ $remaining_seconds -lt 0 ]]; then
+    remaining_seconds=0
+fi
+remaining_minutes=$((remaining_seconds / 60))
+
+session_minutes=$((CURRENT_SESSION_SECONDS / 60))
+
+percentage=$((TOTAL_WORK_SECONDS * 100 / WORK_QUOTA_REQUIRED))
+if [[ $percentage -gt 100 ]]; then
+    percentage=100
+fi
+
+# Display status
+echo ""
+echo "╔════════════════════════════════════════════════════════════════╗"
+echo "║         Bachelor Thesis Work Tracker - Status                 ║"
+echo "╚════════════════════════════════════════════════════════════════╝"
+echo ""
+
+# Work progress
+echo -e "${BOLD}Work Progress:${NC}"
+echo -e "  Total work time: ${GREEN}${work_hours}h ${work_remaining_minutes}m${NC}"
+echo -e "  Required quota:  ${BLUE}${quota_hours}h ${quota_remaining_minutes}m${NC}"
+
+# Progress bar
+echo -n "  Progress: ["
+bar_length=40
+filled=$((percentage * bar_length / 100))
+for ((i=0; i<bar_length; i++)); do
+    if [[ $i -lt $filled ]]; then
+        echo -n "█"
+    else
+        echo -n "░"
+    fi
+done
+echo -e "] ${percentage}%"
+
+# Remaining time
+if [[ $remaining_minutes -gt 0 ]]; then
+    echo -e "  ${YELLOW}Need ${remaining_minutes} more minutes to unlock distractions${NC}"
+else
+    echo -e "  ${GREEN}✓ Quota met! Keep up the good work!${NC}"
+fi
+echo ""
+
+# Access status
+echo -e "${BOLD}Access Status:${NC}"
+if [[ $STEAM_ACCESS_GRANTED -eq 1 ]]; then
+    echo -e "  Steam & Distractions: ${GREEN}UNLOCKED${NC} ✓"
+else
+    echo -e "  Steam & Distractions: ${RED}BLOCKED${NC} ⛔"
+fi
+echo ""
+
+# Current session
+if [[ $LAST_WORK_SESSION_START -ne 0 ]]; then
+    echo -e "${BOLD}Current Session:${NC}"
+    echo -e "  ${GREEN}Active work session in progress${NC}"
+    echo -e "  Session duration: ${session_minutes} minutes"
+    echo ""
+fi
+
+# Service status
+echo -e "${BOLD}Service Status:${NC}"
+if systemctl is-active --quiet "thesis-work-tracker@$(logname).service" 2>/dev/null; then
+    echo -e "  Tracker daemon: ${GREEN}RUNNING${NC} ✓"
+else
+    echo -e "  Tracker daemon: ${RED}NOT RUNNING${NC} ⚠"
+    echo -e "  ${YELLOW}Start with: sudo systemctl start thesis-work-tracker@\$(whoami).service${NC}"
+fi
+echo ""
+
+# Useful commands
+echo -e "${BOLD}Useful Commands:${NC}"
+echo "  • View live logs:     tail -f /var/log/thesis-work-tracker/tracker.log"
+echo "  • Service status:     systemctl status thesis-work-tracker@\$(whoami).service"
+echo "  • Restart tracker:    sudo systemctl restart thesis-work-tracker@\$(whoami).service"
+echo ""