282 lines
6.0 KiB
Markdown
282 lines
6.0 KiB
Markdown
# 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
|
|
|
|
## 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`:
|
|
|
|
```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
|