Add conflict resolution diff UI and app branding

2026-05-13 16:25:28 -04:00
parent 780ff3a02c
commit d359baa010
83 changed files with 4523 additions and 3735 deletions
--- a/.project/milestones/milestone-02-sync-protocol.md
+++ b/.project/milestones/milestone-02-sync-protocol.md
@@ -0,0 +1,143 @@
+# Milestone 2: Sync Protocol
+
+**Duration:** 2 weeks  
+**Goal:** Bidirectional file sync between server and filesystem/web client
+
+## Tasks
+
+### Week 3: Server-Side Sync
+
+- [ ] Content-addressed filesystem implementation
+  - SHA-256 hash computation
+  - Directory layout: `store/ab/cd/abcdef...`
+  - Write-once semantics
+  - Deduplication verification
+  
+- [ ] File watcher (fsnotify)
+  - Watch configured directory recursively
+  - Debounce rapid changes (1s window)
+  - Ignore patterns (.git, temp files)
+  - Compute hash on change, update database
+  
+- [ ] WebSocket server
+  - Connection management (connection pool)
+  - Message framing and parsing
+  - Authentication over WebSocket (token validation)
+  - Heartbeat/ping-pong for connection health
+  
+- [ ] SimpleSync protocol server implementation
+  - Sync request/response handler
+  - Root hash computation (Merkle tree)
+  - Missing content detection
+  - Conflict detection logic
+
+### Week 4: Client-Side Sync & Offline Support
+
+- [ ] WebSocket client (Preact)
+  - Connection management with auto-reconnect
+  - Message queue for offline periods
+  - Exponential backoff for reconnection
+  
+- [ ] IndexedDB cache layer
+  - Store file content by hash
+  - Store sync state and pending changes
+  - LRU eviction for cache management
+  
+- [ ] File sync UI
+  - Sync status indicator
+  - Offline mode banner
+  - Pending changes list
+  - Manual sync trigger button
+  
+- [ ] Conflict detection display
+  - Visual indicator for conflicting files
+  - Basic conflict resolution UI (choose local/server)
+
+## Acceptance Criteria
+
+### Functional
+- [ ] File changes on disk automatically sync to server within 5 seconds
+- [ ] Web client receives real-time updates when files change on server
+- [ ] Client can make changes offline and sync when reconnected
+- [ ] Concurrent edits to different files succeed without conflict
+- [ ] Concurrent edits to same file detected as conflict
+- [ ] Content hash verified on every transfer (client and server)
+- [ ] Sync works across browser refresh (IndexedDB persistence)
+
+### Non-Functional
+- [ ] WebSocket connections authenticated (reject unauthenticated)
+- [ ] File watcher doesn't consume >1% CPU on idle
+- [ ] IndexedDB storage cleared on logout
+- [ ] Sync protocol documented with sequence diagrams
+
+### Performance
+- [ ] Sync of 100 files completes in <10 seconds
+- [ ] WebSocket message overhead <1KB per sync cycle
+- [ ] File watcher detects changes within 500ms
+
+## Protocol Specification
+
+### Message Types
+
+```typescript
+// Client → Server
+interface SyncRequest {
+  type: 'sync_request';
+  clientId: string;
+  rootHash: string;
+  files: Record<string, string>; // path → hash
+}
+
+// Server → Client
+interface SyncResponse {
+  type: 'sync_response';
+  serverRootHash: string;
+  missingFromClient: string[]; // hashes to download
+  missingFromServer: string[]; // hashes to upload
+  conflicts: string[]; // file paths with conflicts
+}
+
+// Content request
+interface ContentRequest {
+  type: 'content_request';
+  hash: string;
+}
+
+// Content response
+interface ContentResponse {
+  type: 'content_response';
+  hash: string;
+  content: string; // base64 encoded
+}
+```
+
+### State Machine
+
+```
+[Idle] --sync_request--> [Comparing] --has_differences--> [Transferring] --complete--> [Idle]
+                                      --no_differences--> [Idle]
+[Idle] --file_change--> [LocalChange] --sync--> [Comparing]
+```
+
+## Deliverables
+
+1. SimpleSync protocol specification document
+2. Sequence diagrams for all sync scenarios
+3. WebSocket API documentation
+4. Offline sync test suite
+
+## Risk Mitigation
+
+| Risk | Mitigation |
+|------|-----------|
+| WebSocket connection drops frequently | Auto-reconnect with exponential backoff, queue offline |
+| Large files cause sync delays | Chunked transfer, progress indicators, size limits |
+| Conflicts in frequently edited files | Optimistic UI, clear conflict resolution, email notification |
+
+## Definition of Done
+
+- [ ] All acceptance criteria pass
+- [ ] Sync protocol tested with 2+ concurrent clients
+- [ ] Offline/online transition tested
+- [ ] Performance benchmarks meet targets
+- [ ] Documentation complete