Feature/sync client - #18

Overview

This PR implements the client-side synchronization infrastructure for docsgraph. It introduces a production-ready HTTP client communicating with docsgraph-server's sync endpoints and an orchestrator (SyncManager) that manages local-to-remote pushing/pulling, handles offline gracefully, and automatically resumes on reconnection.

Key Changes

1. HTTP Sync Client (packages/data/src/sync/client.ts)

• Implemented HttpSyncClient implementing SyncClient using native fetch.
• Connects to standard docsgraph-server sync endpoints:
  • POST /api/v1/sync/push
  • GET /api/v1/sync/pull?since=<cursor>
• Added support for bearer authentication using either a static token or a dynamic evaluation function () => string | null.

2. Sync Manager Orchestration (packages/data/src/sync/manager.ts)

• Created SyncManager coordinating data exchange between LocalStore and SyncClient.
• Workflow:
  1. Push Phase: Detects and pushes unsynced local mutations.
  2. Pull Phase: Fetches remote operations starting from the local cursor, applying them using the store's conflict resolution logic, and updates the local cursor.
• Offline Handling: Gracefully catches fetch failures, transitioning state to offline instead of crashing.
• Reconnection Handling: Subscribes to browser online events to automatically retry sync cycles when connectivity is restored. Includes a configurable polling fallback.
• Avoided any typings entirely to satisfy strict ESLint rules.

3. Verification & Testing (packages/data/src/sync/sync.test.ts)

• Added comprehensive unit tests covering:
  • HttpSyncClient API request body, params, and header validation.
  • SyncManager lifecycle (Happy path pushing/pulling, offline graceful degradation on fetch failure, and automatic retry on online events).
• Safely mocked global window, navigator, and fetch properties using property descriptor overrides to ensure compatibility with strict environments (Node.js/JSDOM).

Verification Results

All tests and code checks run successfully locally:

• pnpm lint: Passed (0 warnings/errors)
• pnpm test: Passed (12/12 tests)