dashboard sync app
This commit is contained in:
Tim Bendt
284
README.md
284
README.md
@@ -1,13 +1,281 @@
|
||||
# LŪK
|
||||
# luk
|
||||
|
||||
> Pronunced Look...
|
||||
> Pronounced "look" - as in "look at your Outlook data locally"
|
||||
|
||||
A collection of tools for syncing microsoft Mail and Calendars with local file-system based PIM standards like Maildir, VDIR, etc so you can use local TUI and CLI tools to read write and manage your mail and events.
|
||||
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
|
||||
|
||||
- Download Emails to a local maildir
|
||||
- Download Events to a local VDIR
|
||||
- two-way sync of locally changed files
|
||||
- View OneDrive Folders and Files in your terminal
|
||||
- a couple different ways to view email messages locally, but you should probably be using [aerc]
|
||||
- **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
|
||||
|
||||
Reference in New Issue
Block a user