HereIAm/README.md

# 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**: `~/.hereiam/logs/hereiam.log` (same directory as config file)
- **Log Persistence**: Logs are persistent across reboots
- **Log Rotation**: Automatic (when DEBUG mode is enabled)
- **Log Levels**: INFO (default) or DEBUG (when DEBUG=True in options)

### Startup Configuration
- **Launch at Startup**: Automatically launch HereIAm when you log in to macOS
- **Implementation**: Uses macOS Launch Agents (`~/Library/LaunchAgents/`)
- **Requirements**: Only available when using the built .app bundle
- **Configuration**: Can be enabled/disabled through the Options dialog

## 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/                 # Source code
│   ├── main.py          # Application entry point and main GUI logic
│   ├── mouse_mover.py   # Mouse monitoring and movement logic
│   ├── config_manager.py # Configuration management
│   ├── logging_config.py # Logging configuration
│   ├── options_dialog.py # Options dialog UI
│   └── utils.py         # Utility functions and safety features
├── assets/              # Application 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)
├── tests/               # Test scripts and test documentation
│   ├── test_config.py   # Configuration tests
│   ├── test_dialog.py   # Dialog functionality tests
│   ├── test_logging.py  # Logging tests
│   ├── test_restart.py  # Restart functionality tests
│   ├── test_app.sh      # App bundle integration tests
│   └── README.md        # Test documentation
├── build_app.sh         # Build script for macOS app bundle
├── create_dmg.sh        # DMG creation script
├── requirements.txt     # Python dependencies
├── requirements-build.txt # Build 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

## Testing

The project includes comprehensive test scripts located in the `tests/` directory.

### Running Tests

**Python Unit Tests:**
```bash
cd tests
python3 test_config.py      # Test configuration management
python3 test_dialog.py      # Test options dialog
python3 test_logging.py     # Test logging functionality
python3 test_restart.py     # Test restart functionality
```

**Application Bundle Test:**
```bash
cd tests
./test_app.sh               # Test built macOS app bundle
```

**Note:** Make sure to build the application first with `./build_app.sh` before running app bundle tests.

4. **Testing Startup Functionality**:
   ```bash
   ./test_startup.py
   ```

For detailed testing information, see [tests/README.md](tests/README.md).

## 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 `~/.hereiam/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 the Options dialog: set Log Level to "DEBUG"
2. Run from terminal to see console output
3. Check `~/.hereiam/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.*