Add IMAP to Nextcloud Calendar importer

- IMAP mailbox monitoring with SSL/TLS, STARTTLS and plain connection support
- ICS attachment extraction from emails and import to Nextcloud via CalDAV
- Create or update calendar events by UID to avoid duplicates
- Event filtering by summary (contains, regex or exact match, with inversion)
- Deduplication by regex pattern extracted from event summaries
- Move or mark processed emails as seen after import
- Continuous polling mode and one-time run mode
- Fully configurable via environment variables
- Docker and Docker Compose support
- Test suite with pytest

CLAUDE.md

@@ -0,0 +1,81 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+IMAP to Nextcloud Calendar Importer - A Python utility that monitors an IMAP mailbox for emails with ICS calendar attachments and imports them to a Nextcloud calendar via CalDAV.
+
+## Commands
+
+### Build and Run
+```bash
+# Build Docker image
+docker build -t imap-calendar-importer .
+
+# Run with Docker Compose (continuous mode)
+docker-compose up -d
+
+# Run once and exit
+docker-compose run --rm imap-calendar-importer
+
+# View logs
+docker-compose logs -f
+
+# Rebuild after code changes
+docker-compose up -d --build
+```
+
+### Direct Python Execution
+```bash
+# Install dependencies
+pip install -r requirements.txt
+
+# Run directly (requires .env or environment variables set)
+python imap_calendar_importer.py
+```
+
+### Testing
+```bash
+# Create virtual environment and install dependencies
+python -m venv .venv
+.venv/bin/pip install -r requirements.txt
+
+# Run all tests
+.venv/bin/pytest tests/ -v
+
+# Run specific test class
+.venv/bin/pytest tests/test_imap_calendar_importer.py::TestMatchesFilter -v
+
+# Run with coverage (requires pytest-cov)
+.venv/bin/pytest tests/ --cov=imap_calendar_importer --cov-report=term-missing
+```
+
+## Architecture
+
+Single-file Python application (`imap_calendar_importer.py`) with one main class:
+
+**`IMAPCalendarImporter`** - Handles the complete workflow:
+1. `connect_imap()` - Establishes IMAP connection (SSL/TLS, STARTTLS, or plain)
+2. `connect_caldav()` - Connects to Nextcloud CalDAV and discovers target calendar
+3. `process_emails()` - Searches for unseen emails, extracts ICS attachments
+4. `extract_ics_attachments()` - Parses MIME messages, applies summary filtering
+5. `import_ics_to_calendar()` - Creates new or updates existing events by UID
+
+**Execution Modes:**
+- Continuous: Polls mailbox every `CHECK_INTERVAL` seconds
+- One-time: Processes once and exits (`RUN_ONCE=true`)
+
+## Configuration
+
+All configuration via environment variables (see `.env.sample`). Key settings:
+- `IMAP_*` - Mail server connection (server, port, credentials, SSL options)
+- `CALDAV_*` - Nextcloud connection (URL, credentials, calendar name)
+- `SUMMARY_FILTER*` - Event filtering by title (contains/regex/exact, with inversion)
+- `RUN_ONCE` / `CHECK_INTERVAL` - Execution mode control
+
+## Dependencies
+
+- `caldav` - CalDAV client library
+- `icalendar` - ICS parsing
+- `urllib3` - HTTP client (used by caldav)