Skip to content

HANDOFF.md

Latest commit

 

History

History
101 lines (74 loc) · 3.79 KB

HANDOFF.md

File metadata and controls

101 lines (74 loc) · 3.79 KB
Raw

Handoff

Project

~/Projects/logseq-nextcloud-sync

This is a standalone Logseq plugin project, moved out from the earlier monorepo workspace. It is now symlinked into:

~/.logseq/plugins/logseq-nextcloud-sync

GitHub repository:

https://github.com/olterman/logseq-nextcloud-sync

Git remote origin is configured to use HTTPS:

https://github.com/olterman/logseq-nextcloud-sync.git

Current architecture

  • src/main.ts Plugin entry point, settings schema, command registration, renderer-backed UI pages, task-scope manager flow, calendar selector flow.
  • src/caldav.ts Task collection, task sync, task-list discovery, task-list creation, task completion mirroring, scope-aware task filtering.
  • src/calendar.ts Calendar event collection, calendar sync, calendar discovery, calendar selector support.
  • src/types.ts Shared plugin settings and domain types.

Implemented features

  • Generic task sync, not tied to the academia plugin structure.
  • Scopeable task filtering by page type and/or page tags.
  • Multiple saved task scopes, each with:
    • name
    • page-type filter string
    • tag filter string
    • bound Nextcloud task-list URL
    • enabled flag
  • Active scope selection.
  • Sync-one-scope and sync-all-enabled-scopes flows.
  • Discovery of Nextcloud VEVENT calendars.
  • Discovery of Nextcloud VTODO task lists.
  • Creation of remote Nextcloud VTODO task lists for the active scope.
  • Selector/manager pages rendered inside Logseq.
  • ICS export for tasks and calendar events.
  • Mirroring of remote completed tasks back into matching Logseq blocks.
  • Plugin metadata files now exist for Logseq UI / packaging:
    • manifest.json
    • LICENSE
    • enriched metadata in package.json

Important UI pages

  • Nextcloud Tasklist Scopes Main task scope manager.
  • Nextcloud Calendar Picker Calendar discovery and selection page.
  • Nextcloud Tasks Snapshot page for the currently refreshed/active scope.
  • Nextcloud Calendar Snapshot page for discovered calendar events.

These pages are generated by the plugin and are rewritten by the plugin when refreshed or ensured.

Important compatibility note

There is a compatibility fallback from the older single-scope model:

  • If taskScopesJson is empty, the plugin synthesizes a legacy default scope from:
    • caldavTaskListUrl
    • taskFilterPageTypes
    • taskFilterTags

Once named scopes are created and saved, those become the primary source of truth.

Code review findings to keep in mind

The latest review surfaced a few correctness risks that have not been fixed yet:

  1. state.tasks is shared across scopes in src/main.ts, so previewing one scope can leave cached tasks that later get synced for another scope.
  2. The task sync cache in src/caldav.ts is global rather than per-scope/per-task-list, so delete tracking is unreliable across multiple saved scopes.
  3. CANCELLED tasks are currently flattened into COMPLETED / DONE semantics during sync and mirror-back.
  4. The overview/helper pages are destructively rewritten, so custom content on those pages will be removed.

Suggested next steps

  1. Fix scope-specific task caching in src/main.ts so previewing one scope cannot affect syncing another scope.
  2. Make task sync cache storage scope-aware or task-list-aware in src/caldav.ts.
  3. Preserve cancellation state distinctly instead of mapping it to completion.
  4. Decide whether generated pages should stay destructive or move to safer append/managed-block behavior.
  5. Add delete/duplicate controls for task scopes in the manager UI.
  6. Add per-scope test-connection UI and per-scope export UI buttons.
  7. Consider replacing prompt-based scope editing with a richer in-page form.

Verification completed

  • ./node_modules/.bin/tsc -p tsconfig.json --noEmit
  • node esbuild.mjs

Both were passing at the latest handoff update.