[Feature]: RFC 5545 iCalendar Subscription Feeds (/pm calendar & webcal feed)

[espdesign]

Summary

Provide personalized, live iCalendar subscription feeds (.ics / webcal://) for Discord contributors and server members, enabling direct synchronization of assigned tasks and due dates into Google Calendar, Apple Calendar, Microsoft Outlook, and standard task management clients.

Background & Context

From Day 1, dgg-pm has prioritized RFC 5545 schema portability (to_rfc5545_vtodo in src/domain/standard_mappings.py, mapping TaskStatus and PriorityLevel to RFC 5545 values). Furthermore, a concurrent FastAPI server (src/adapters/api/app.py) is already running within the application process on port 8000.

Currently, contributors must check Discord to track their deadlines and upcoming commitments. Offering an iCal subscription link allows users to view their active and overdue project tasks directly within their personal calendar apps.

Proposed Capabilities

1. Calendar Token & Security:

   • Add secure token generation for each Discord user (e.g., stateful calendar_token in user_preferences table or HMAC-signed token).
   • Allow users to reset / revoke their calendar link on demand if compromised.

2. Calendar Export & Client Compatibility:

   • Wrap task RFC 5545 components into a valid VCALENDAR envelope (BEGIN:VCALENDAR ... END:VCALENDAR).
   • Support VEVENT serialization for tasks with due_at to ensure full visibility on calendar clients that ignore VTODO (specifically Google Calendar web UI).
   • Support VTODO serialization (?format=todo) for dedicated to-do and task clients (Apple Reminders, OmniFocus).

3. HTTP Calendar Endpoint in FastAPI:

   • Expose GET /calendar/{token}.ics in src/adapters/api/app.py returning text/calendar; charset=utf-8.
   • Query user's assigned active tasks across authorized projects and render the RFC 5545 calendar feed.

4. Discord Bot Interface:

   • Add /pm calendar slash command (or an interactive button within /pm settings / /pm task list).
   • Ephemerally reply with:
     • Direct webcal:// link (one-click subscription in macOS/iOS/Windows calendar clients).
     • Standard https:// link (for manual entry in Google Calendar / Outlook).
     • Interactive "Regenerate Link" button.

5. Configuration & Documentation:

   • Add PUBLIC_BASE_URL in src/config.py (e.g. https://pm.example.com).
   • Document reverse-proxy setup (Caddy/Nginx/Cloudflare Tunnel) in README.md and docs/wiki.

Acceptance Criteria

• Users can retrieve their private calendar subscription URL via /pm calendar.
• Calendar feeds served over GET /calendar/{token}.ics validate cleanly against RFC 5545 linters.
• Google Calendar, Apple Calendar, and Outlook successfully import and display assigned tasks with due dates.
• Users can regenerate/revoke their calendar token at any time.
• Unauthenticated or invalid tokens return 401/404 without leaking user or task information.
• Unit and integration tests covering token generation, FastAPI route, calendar payload generation, and cog commands.