sirtimbly/luk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
9a2f8ee211aa978beaacd867f6f248b26750fa54
luk/luk.egg-info/PKG-INFO
Bendt a41d59e529 WIP
2025-12-18 22:11:47 -05:00

327 lines
7.8 KiB
Plaintext
Raw Blame History

Metadata-Version: 2.4
Name: luk
Version: 0.1.0
Summary: A CLI tool for syncing Microsoft Outlook email, calendar, and tasks to local file-based formats. Look at your Outlook data locally.
Author-email: Timothy Bendt <timothy@example.com>
License: MIT
Project-URL: Homepage, https://github.com/timothybendt/luk
Project-URL: Repository, https://github.com/timothybendt/luk
Project-URL: Issues, https://github.com/timothybendt/luk/issues
Project-URL: Documentation, https://github.com/timothybendt/luk#readme
Keywords: email,calendar,tasks,sync,cli,microsoft-graph,outlook,maildir,vdir
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Email
Classifier: Topic :: Office/Business :: Scheduling
Classifier: Topic :: Utilities
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: aiohttp>=3.11.18
Requires-Dist: certifi>=2025.4.26
Requires-Dist: click>=8.1.0
Requires-Dist: html2text>=2025.4.15
Requires-Dist: mammoth>=1.9.0
Requires-Dist: markitdown[all]>=0.1.1
Requires-Dist: msal>=1.32.3
Requires-Dist: openai>=1.78.1
Requires-Dist: orjson>=3.10.18
Requires-Dist: pillow>=11.2.1
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: python-dateutil>=2.9.0.post0
Requires-Dist: python-docx>=1.1.2
Requires-Dist: requests>=2.31.0
Requires-Dist: rich>=14.0.0
Requires-Dist: textual>=3.2.0
Requires-Dist: textual-image>=0.8.2
Requires-Dist: ticktick-py>=2.0.0
Requires-Dist: toml>=0.10.0
# 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
Reference in New Issue View Git Blame Copy Permalink