# HereIAm - Mouse Movement Monitor

## Overview
HereIAm is a sophisticated macOS application that runs discretely in the system menu bar. It intelligently monitors mouse activity and automatically moves the cursor to prevent system inactivity when needed. The application features a clean PyQt5-based interface with adaptive theming and comprehensive logging.

## Features

### Core Functionality
- **Smart Mouse Monitoring**: Tracks mouse position and automatically moves cursor after a configurable period of inactivity
- **System Menu Bar Integration**: Runs as a native macOS menu bar application with context menu controls
- **Adaptive Icon Theming**: Automatically adjusts icons based on system dark/light mode
- **Thread-Safe Operation**: Mouse monitoring runs in a separate thread for responsive UI

### User Interface
- **Right-click Context Menu**: Easy enable/disable controls with visual status indicators
- **Double-click Toggle**: Quick enable/disable by double-clicking the menu bar icon
- **About Dialog**: Displays application information and version details
- **Status Display**: Real-time status indication in the context menu

### Advanced Features
- **Comprehensive Logging**: Detailed logging with configurable levels (DEBUG/INFO)
- **Error Handling**: Robust error handling and recovery mechanisms
- **Configuration Management**: Centralized configuration with easy customization
- **System Integration**: Proper macOS system tray integration with fail-safes

## Installation

### Prerequisites
- macOS (tested on macOS 10.14+)
- Python 3.8 or higher
- System with menu bar/system tray support

### Setup Steps

1. **Clone the repository:**
   ```bash
   git clone <repository-url>
   cd HereIAm
   ```

2. **Create a virtual environment (recommended):**
   ```bash
   python3 -m venv .venv
   source .venv/bin/activate
   ```

3. **Install dependencies:**
   ```bash
   pip install -r requirements.txt
   ```

4. **Install as package (optional):**
   ```bash
   pip install -e .
   ```

## Usage

### Running the Application

**From source:**
```bash
python src/main.py
```

**If installed as package:**
```bash
hereiam
```

### Using the Application

1. **Launch**: The application will appear in your menu bar with an icon
2. **Enable/Disable**: Right-click the icon to access the context menu
3. **Quick Toggle**: Double-click the icon for instant enable/disable
4. **Status Monitoring**: The icon changes to indicate current state:
   - ✅ **Enabled**: Green icon when mouse monitoring is active
   - ❌ **Disabled**: Gray icon (theme-aware) when monitoring is off

### Menu Options
- **Status**: Shows current monitoring state
- **Enable HereIAm**: Starts mouse movement monitoring
- **Disable HereIAm**: Stops mouse movement monitoring  
- **About HereIAm**: Application information and version
- **Quit**: Cleanly exits the application

## Configuration

### Main Settings (`src/config.py`)
```python
WAITTIME = 240      # Wait time in seconds before moving mouse (default: 4 minutes)
MovePx = 10         # Pixels to move mouse (default: 10px)
StartEnabled = True # Start with monitoring enabled (default: True)
DEBUG = False       # Enable debug logging (default: False)
```

### Logging Configuration
- **Log Location**: `logs/hereiam.log`
- **Log Rotation**: Automatic (when DEBUG mode is enabled)
- **Log Levels**: INFO (default) or DEBUG (when DEBUG=True)

## Dependencies

### Core Runtime Dependencies
- **PyQt5** (≥5.15.0): GUI framework and system tray integration
- **pyautogui** (≥0.9.54): Mouse movement and position detection
- **pyobjc-framework-Cocoa** (≥9.0): macOS system integration
- **pyobjc-framework-Quartz** (≥9.0): macOS graphics and display APIs

### Development Dependencies (Optional)
- **pytest** (≥7.0.0): Testing framework
- **black** (≥22.0.0): Code formatting
- **flake8** (≥4.0.0): Code linting

## Project Structure
```
HereIAm/
├── src/
│   ├── main.py          # Application entry point and main GUI logic
│   ├── mouse_mover.py   # Mouse monitoring and movement logic
│   ├── config.py        # Configuration and logging setup
│   └── utils.py         # Utility functions and safety features
├── assets/
│   ├── Enabled.icns     # Icon for enabled state
│   ├── Disabled-Light.icns  # Icon for disabled state (light theme)
│   └── Disabled-Dark.icns   # Icon for disabled state (dark theme)
├── logs/                # Application logs (created at runtime)
├── requirements.txt     # Python dependencies
├── setup.py            # Package installation configuration
└── README.md           # This file
```

## Technical Details

### Architecture
- **Main Application** (`main.py`): PyQt5-based GUI with system tray integration
- **Mouse Monitor** (`mouse_mover.py`): Threaded mouse position tracking and automatic movement
- **Configuration** (`config.py`): Centralized settings and logging configuration
- **Utilities** (`utils.py`): Safety features and error handling for mouse operations

### How It Works
1. **Monitoring**: The application continuously tracks mouse position in a background thread
2. **Timer Management**: A countdown timer resets whenever mouse movement is detected
3. **Automatic Movement**: When the timer expires, the mouse is moved slightly and returned to position
4. **User Feedback**: The menu bar icon and status reflect the current monitoring state

### Safety Features
- **Bounds Checking**: Mouse movements are constrained to screen boundaries
- **Error Recovery**: Comprehensive exception handling prevents crashes
- **Graceful Shutdown**: Clean thread termination and resource cleanup
- **Fail-Safe Integration**: PyAutoGUI safety features configured appropriately

## Troubleshooting

### Common Issues

**Application doesn't appear in menu bar:**
- Ensure system tray is available on your system
- Check that PyQt5 is properly installed
- Verify you have necessary permissions for GUI applications

**Mouse movement not working:**
- Check that accessibility permissions are granted to Terminal/Python
- Verify pyautogui installation: `python -c "import pyautogui; print('OK')"`
- Review logs in `logs/hereiam.log` for error details

**Icons not displaying:**
- Verify all `.icns` files are present in the `assets/` directory
- Check file permissions on the assets folder
- Enable DEBUG mode in config.py for detailed icon loading logs

### Debugging
1. Enable debug mode in `src/config.py`: `DEBUG = True`
2. Run from terminal to see console output
3. Check `logs/hereiam.log` for detailed operation logs
4. Use Activity Monitor to verify the application is running

## Development

### Building from Source
```bash
# Setup development environment
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# Run in development mode
python src/main.py
```

### Building for Distribution

#### Create macOS .app Bundle
```bash
# Install build dependencies
pip install -r requirements-build.txt

# Build the application
./build_app.sh
```

This creates `dist/HereIAm.app` - a standalone application bundle.

#### Create Distribution DMG
```bash
# Create installer DMG
./create_dmg.sh
```

This creates `dist/HereIAm-1.0.0.dmg` ready for distribution.

#### Full Distribution Workflow
```bash
# Complete build and package process
./build_app.sh && ./create_dmg.sh
```

See [DISTRIBUTION.md](DISTRIBUTION.md) for detailed building, code signing, and distribution instructions.

### Creating a Standalone App (macOS)
```bash
# Install PyInstaller
pip install pyinstaller

# Create app bundle
pyinstaller --windowed --onefile --add-data "assets:assets" --icon="assets/Enabled.icns" src/main.py
```

## Author & Support

**Author:** Jerico Thomas  
**Email:** jerico@tekop.net  
**Version:** 1.0.0

## License
This project is licensed under the MIT License. See the LICENSE file for details.

---

*HereIAm - Keeping your Mac awake, one mouse movement at a time.*