nocal/docs/ROADMAP.md

Roadmap

Foundation — current milestone

• C++20 domain model and deterministic six-week month layout
• Responsive, theme-native ANSI month view with keyboard navigation
• Appointment focus, dense-day traversal, and full-frame detail reader
• Validated add/edit/delete forms with confirmation and failure rollback
• Guarded atomic .ics persistence, advisory locking, and round-trip tests
• Bounded session undo/redo, exact external-change detection, and backup recovery
• Windowed recurrence expansion, compatible RDATE, EXDATE, IANA TZID, and multi-day segment cues
• Occurrence-aware appointment search with exact result-to-grid navigation
• Session calendar toggles shared by month rendering, focus, and search
• Read-only 42-day agenda with bounded recurrence and exact return navigation
• Configurable week start with Monday-default CLI and consistent grid queries
• Explicit atomic import/export with validation, collision refusal, and backups
• Meson build, Nix development shell, desktop entry, and Hyprland launcher
• Seeded sample data when explicitly requested, never silent data mutation

0.1 — complete local calendar

• Advanced recurrence rule editing and detached RECURRENCE-ID overrides
• Embedded VTIMEZONE support
• Screen-reader-friendly linear view and full Unicode display-width handling

0.2 — durable cache and provider boundary — in progress

Completed cache foundation:

• Provider-neutral SQLite WAL cache in a private local file
• Versioned, all-or-nothing schema migrations
• Raw provider payload retention, inactive calendars, and event tombstones
• Per-calendar/window opaque cursors committed atomically with pulled pages
• Normalized event instances for immutable snapshots
• Reserved transactional outbox and conflict records for later remote writes

Completed HTTP/OAuth boundary:

• Generic injected HTTP transport and deterministic fakes, with retries left to provider operations
• Public-desktop OAuth authorization code design with PKCE S256, system browser, and loopback redirect
• Multitenant Microsoft account audience and delegated least-privilege Calendars.Read; tenant policy may still require administrator consent or block user consent
• No client secret in the open-source desktop binary

Completed concrete Linux adapters:

• libcurl transport with verified TLS, bounded responses/timeouts, no automatic redirects/retries, and cleartext HTTP only for loopback tests
• Shell-free xdg-open launcher and one-shot 127.0.0.1 callback receiver advertising http://localhost:<dynamic-port>/nocal/oauth/callback
• Mobile/Desktop public-client registration at http://localhost/nocal/oauth/callback; Microsoft ignores localhost ports, while literal HTTP 127.0.0.1 needs a manifest edit and IPv6 loopback is not supported

Completed token/secret boundary:

• Strict, bounded token JSON parsing with a required initial refresh token
• Refresh-token rotation with retention of the previous token when a refresh response omits a replacement
• Versioned libsecret payloads keyed by opaque local account IDs
• Synchronous, cancellable Secret Service calls restricted to worker threads
• Real isolated D-Bus/gnome-keyring integration tests
• Explicit missing, locked, cancelled, and failure results; no connected account until the complete secret store succeeds
• OAuth secrets only in Secret Service, never SQLite, logs, CLI arguments, or environment variables

Completed Microsoft Graph read phase:

• Public desktop multitenant organizational/personal account support
• Delegated User.Read for /me and Calendars.Read for calendars/events; tenant policy may still require approval or block user consent
• Per-operation access tokens with persistent tokens retained only by Secret Service
• Complete paged all-calendar discovery with atomic cache replacement and deterministic local IDs
• Immutable Graph event IDs, strict bounded parsing, and credential-safe errors
• HTTPS graph.microsoft.com-only opaque continuation/delta links
• Half-open UTC event windows and per-page event/tombstone/cursor transactions
• Resumable primary-calendar v1 delta synchronization

Completed secondary-calendar stable-v1 reconciliation:

• Documented per-calendar calendarView reads with complete bounded paging
• Schema-v2 durable per-window event membership
• Atomic complete-window replacement after every page validates
• Range omission distinguished from a remote deletion tombstone
• Overlapping windows retain events until their last membership is removed
• No beta or undocumented per-calendar delta dependency

Completed provider-boundary contracts and token broker:

• Generic SyncProvider/SyncObserver contracts for account connect, sync, and disconnect with staged progress events
• OAuthTokenBroker returning valid per-operation access tokens with a five-minute refresh skew
• Refresh rotation persisted before use so a new refresh token is never lost; transient refresh failures leave stored credentials untouched
• 400/401 refresh rejections erase the stored secret and surface AccountDisconnected for re-authentication
• Credential material never appears in exception messages

Completed account setup (CLI):

• nocal account connect microsoft runs the PKCE browser flow, reads /me, upserts the deterministic account row, and persists tokens to Secret Service as the final connected-state gate
• Deterministic local account IDs hashed from the remote subject make reconnect idempotent; a secret-store failure leaves the same coherent state as a disconnect
• Placeholder client ID with NOCAL_MICROSOFT_CLIENT_ID override until a real Entra mobile/desktop registration exists
• Deterministic failure-path tests: rejection, token errors, identity failure, storage failure, and credential redaction in error messages

Next provider-boundary slices:

• TUI account orchestration and generic SyncProvider integration with observable sync status

0.3 — CalDAV

• Discovery and incremental sync for Nextcloud and standards-compliant servers
• ETag-aware writes, offline mutation queue, conflict UI
• TLS and failure-path integration tests

0.4 — hosted providers

• Google Calendar adapter with incremental synchronization
• Microsoft 365 read-only discovery and Graph delta synchronization, followed by ETag-aware remote writes after the conflict boundary is proven
• Account/calendar management UI and per-calendar ANSI identity

The Graph read boundary uses stable v1 delta for the primary calendar and complete stable-v1 calendar views for secondary calendars; it deliberately avoids beta and undocumented per-calendar delta routes. Account connect exists as a CLI command with live credential integration through Secret Service, but there is no account TUI or sync orchestration yet, and remote writes remain out of scope.

1.0 — distribution quality

• Stable configuration/data format and documented recovery procedures
• Nomarchy package, Hyprland defaults, man page, shell completions
• Performance budgets exercised against large and adversarial calendars
• Fuzzed iCalendar parser, accessibility review, translations

Quality gates

Every milestone requires clean warning-enabled builds, unit and integration tests, sanitizer runs, terminal-state recovery after signals/errors, no network access without explicit account setup, and no loss of unknown calendar data.