# luk

> Pronounced "look" - as in "look at your Outlook data locally"

A CLI tool for syncing Microsoft Outlook email, calendar, and tasks to local file-based formats like Maildir and vdir. Use your favorite terminal tools to manage your email and calendar.

## Features

- **Email Synchronization**: Sync emails with Microsoft Graph API to local Maildir format
- **Calendar Management**: Two-way calendar sync with vdir/ICS support
- **Task Integration**: Sync with Godspeed and TickTick task managers
- **TUI Dashboard**: Interactive terminal dashboard for monitoring sync progress
- **Daemon Mode**: Background daemon with proper Unix logging
- **Cross-Platform**: Works on macOS, Linux, and Windows
- **Smart Notification Compression**: Automatically detects and compresses transactional notification emails (GitLab, GitHub, Jira, Confluence, Datadog, Renovate) into terminal-friendly summaries

## Quick Start

### Prerequisites

- Python 3.12 or higher
- `uv` package manager (recommended)

### Installation

```bash
# Clone the repository
git clone https://github.com/timothybendt/luk.git
cd luk

# Run the installation script
./install.sh
```

### Manual Installation

```bash
# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -e .

# Setup configuration directories
mkdir -p ~/.config/luk
mkdir -p ~/.local/share/luk
```

## Configuration

Create a configuration file at `~/.config/luk/config.env`:

### Notification Email Compression

LUK includes intelligent notification email compression to reduce visual noise from automated emails (GitLab, GitHub, Jira, Confluence, Datadog, Renovate). Configure it in `~/.config/luk/mail.toml`:

```toml
[content_display]
# Enable/disable notification compression
compress_notifications = true

# Compression mode:
# - "summary": Brief one-page view (default)
# - "detailed": More details in structured format
# - "off": Disable compression, show full emails
notification_compression_mode = "summary"
```

**Features:**
- **Automatic detection**: Identifies notification emails by sender domain and subject patterns
- **Type-specific summaries**: Extracts relevant info per platform (pipeline IDs, PR numbers, etc.)
- **Terminal-friendly formatting**: Clean markdown with icons and clear hierarchy
- **Toggle support**: Press `m` in mail view to switch between compressed and full email

**Demo:**
```bash
python demo_notification_compression.py
```

See `mail.toml.example` for full configuration options.

### General Configuration

```bash
# Microsoft Graph settings
MICROSOFT_CLIENT_ID=your_client_id
MICROSOFT_TENANT_ID=your_tenant_id

# Email settings
MAILDIR_PATH=~/Mail
NOTES_DIR=~/Documents/Notes

# Godspeed settings
GODSPEED_EMAIL=your_email@example.com
GODSPEED_PASSWORD=your_password
GODSPEED_TOKEN=your_token
GODSPEED_SYNC_DIR=~/Documents/Godspeed

# TickTick settings
TICKTICK_CLIENT_ID=your_client_id
TICKTICK_CLIENT_SECRET=your_client_secret
```

## Usage

### Basic Commands

```bash
# Show help
luk --help

# Run sync with default settings
luk sync run

# Run with TUI dashboard
luk sync run --dashboard

# Start daemon mode
luk sync run --daemon

# Stop daemon
luk sync stop

# Check daemon status
luk sync status
```

### Sync Options

```bash
# Dry run (no changes)
luk sync run --dry-run

# Specify organization
luk sync run --org mycompany

# Enable notifications
luk sync run --notify

# Download attachments
luk sync run --download-attachments

# Two-way calendar sync
luk sync run --two-way-calendar

# Custom calendar directory
luk sync run --vdir ~/Calendars
```

### Dashboard Mode

The TUI dashboard provides real-time monitoring of sync operations:

- **Status Display**: Current sync status and metrics
- **Progress Bars**: Visual progress for each sync component
- **Activity Log**: Scrollable log of all sync activities
- **Keyboard Shortcuts**:
  - `q`: Quit dashboard
  - `l`: Toggle log visibility
  - `r`: Refresh status

### Daemon Mode

Run luk as a background daemon with proper Unix logging:

```bash
# Start daemon
luk sync run --daemon

# Check status
luk sync status

# View logs
cat ~/.local/share/luk/luk.log

# Stop daemon
luk sync stop
```

Daemon logs are stored at `~/.local/share/luk/luk.log` with automatic rotation.

## Architecture

### Core Components

- **Sync Engine**: Handles email, calendar, and task synchronization
- **TUI Dashboard**: Interactive monitoring interface using Textual
- **Daemon Service**: Background service with logging and process management
- **Configuration**: Environment-based configuration system

### Directory Structure

```
src/
├── cli/                    # CLI commands and interfaces
│   ├── sync.py            # Main sync command
│   ├── sync_dashboard.py  # TUI dashboard
│   ├── sync_daemon.py     # Daemon service
│   └── ...
├── services/              # External service integrations
│   ├── microsoft_graph/   # Microsoft Graph API
│   ├── godspeed/         # Godspeed task manager
│   ├── ticktick/         # TickTick API
│   └── ...
└── utils/                 # Utility functions
```

## Development

### Setup Development Environment

```bash
# Clone repository
git clone https://github.com/timothybendt/luk.git
cd luk

# Install development dependencies
uv sync --dev

# Run tests
uv run pytest

# Run linting
uv run ruff check .
uv run ruff format .

# Type checking
uv run mypy src/
```

### Project Structure

- `pyproject.toml`: Project configuration and dependencies
- `src/cli/`: CLI commands and user interfaces
- `src/services/`: External service integrations
- `src/utils/`: Shared utilities and helpers
- `tests/`: Test suite

### Building for Distribution

```bash
# Build package
uv run build

# Check package
uv run twine check dist/*

# Upload to PyPI (for maintainers)
uv run twine upload dist/*
```

## Troubleshooting

### Common Issues

1. **Authentication Errors**: Ensure Microsoft Graph credentials are properly configured
2. **Permission Denied**: Check file permissions for Maildir and calendar directories
3. **Daemon Not Starting**: Verify log directory exists and is writable
4. **TUI Not Rendering**: Ensure terminal supports Textual requirements

### Debug Mode

Enable debug logging:

```bash
export LOG_LEVEL=DEBUG
luk sync run --dry-run
```

### Log Files

- **Daemon Logs**: `~/.local/share/luk/luk.log`
- **Sync State**: `~/.local/share/luk/sync_state.json`
- **Configuration**: `~/.config/luk/`

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run the test suite
6. Submit a pull request

### Code Style

This project uses:
- **Ruff** for linting and formatting
- **MyPy** for type checking
- **Black** for code formatting
- **Pre-commit** hooks for quality control

## License

MIT License - see LICENSE file for details.

## Support

- **Issues**: [GitHub Issues](https://github.com/timothybendt/luk/issues)
- **Documentation**: [GitHub Wiki](https://github.com/timothybendt/luk/wiki)
- **Discussions**: [GitHub Discussions](https://github.com/timothybendt/luk/discussions)

## Changelog

### v0.1.0
- Initial release
- Email synchronization with Microsoft Graph
- Calendar sync with vdir/ICS support
- Godspeed and TickTick integration
- TUI dashboard
- Daemon mode with logging
- Cross-platform support