Initial commit: LinkSyncServer and LinkSyncExtension projects with complete documentation, models, API endpoints, tests, and extension implementation

LinkSyncExtension/tasks.md

@@ -0,0 +1,257 @@
+# LinkSyncExtension - Implementation Tasks
+
+## Phase 1: Project Setup
+
+### Setup Tasks
+- [x] Create project directory structure
+- [x] Write README.md
+- [ ] Write TODOs.txt
+- [ ] Write design.md
+- [ ] Write tasks.md
+- [ ] Write AGENTS.md
+
+### Initial Files
+- [ ] Create manifest.json
+- [ ] Add icon files (48x48, 96x96)
+- [ ] Create styles folder with base.css
+- [ ] Create utils folder structure
+
+## Phase 2: Core Development
+
+### Background Script
+- [ ] Create background.html
+- [ ] Create background.js
+- [ ] Implement init() on install/update
+- [ ] Implement sync loop with interval
+- [ ] Add event handlers (message, install, update)
+- [ ] Implement sync mode switching
+- [ ] Add collection mapping logic
+- [ ] Implement auto-sync timer
+- [ ] Add error handling and retries
+
+### Popup Script
+- [ ] Create popup.html
+- [ ] Create popup.css
+- [ ] Create popup.js
+- [ ] Implement bookmark form UI
+- [ ] Add bookmark list view
+- [ ] Implement search filter
+- [ ] Add collection panel
+- [ ] Implement settings UI
+- [ ] Add sync button handler
+
+### Utility Modules
+- [ ] Create utils/bookmark.js
+  - Parse Firefox bookmark data
+  - Format bookmark for API
+  - Handle field validation
+  
+- [ ] Create utils/collection.js
+  - List collections API
+  - Execute query on collection
+  - Create static collection
+  - Update collection name
+  
+- [ ] Create utils/query-engine.js
+  - Tokenize query expression
+  - Build AST
+  - Validate query syntax
+  - Serialize AST to JSON
+  
+- [ ] Create utils/sync.js
+  - Implement sync mode logic
+  - Handle bi-directional sync
+  - Handle browser-authoritative sync
+  - Handle server-authoritative sync
+  - Apply deletions filter
+  - Conflict detection
+  - Conflict resolution
+
+### API Client
+- [ ] Create API request helper
+- [ ] Implement /api/auth/login/
+- [ ] Implement /api/links/ CRUD
+- [ ] Implement /api/collections/ CRUD
+- [ ] Implement /api/queries/execute/
+- [ ] Implement /api/sync/
+- [ ] Add error handling
+- [ ] Add retry logic
+- [ ] Add timeout handling
+
+### Content Script (Optional)
+- [ ] Create content/content.js
+- [ ] Implement page title extraction
+- [ ] Implement URL detection
+- [ ] Implement meta description extraction
+- [ ] Inject popup trigger
+- [ ] Handle content script permissions
+
+## Phase 3: Storage Management
+
+### Storage Implementation
+- [ ] Implement localStorage wrapper
+- [ ] Add encryption for API keys
+- [ ] Implement storage helper functions
+- [ ] Add sync timestamp tracking
+- [ ] Add pending changes counter
+
+### Storage Keys
+- [ ] `linksync_api_key` - JWT token
+- [ ] `linksync_collection` - Collection name
+- [ ] `linksync_sync_mode` - Sync mode string
+- [ ] `linksync_deletions` - Boolean
+- [ ] `linksync_auto_sync` - Boolean
+- [ ] `linksync_last_sync` - ISO timestamp
+- [ ] `linksync_pending` - Integer count
+
+## Phase 4: Sync Logic
+
+### Bi-directional Sync
+- [ ] Push browser→server
+- [ ] Push server→browser
+- [ ] Merge conflicting updates
+- [ ] Track both versions
+
+### Browser Authoritative Sync
+- [ ] Push browser→server
+- [ ] Overwrite server→browser
+- [ ] No pull from server
+
+### Server Authoritative Sync
+- [ ] Download from server
+- [ ] Overwrite local on conflict
+- [ ] No push to server
+
+### Deletions
+- [ ] Implement deletions checkbox logic
+- [ ] Delete on both sides if enabled
+- [ ] Log deletions
+
+### Conflict Resolution
+- [ ] Detect URL collision
+- [ ] Present resolution UI
+- [ ] Keep browser version (default)
+- [ ] Keep server version option
+- [ ] Manual merge option
+
+## Phase 5: UI Components
+
+### Bookmark Form
+- [ ] URL input (auto-fill)
+- [ ] Title input (auto-fill)
+- [ ] Description textarea
+- [ ] Notes textarea
+- [ ] Tags input (comma-separated)
+- [ ] Folder path input
+- [ ] Add/Edit/Delete buttons
+
+### Bookmark List
+- [ ] Pagination
+- [ ] Search filter input
+- [ ] Checkboxes for selection
+- [ ] Batch delete button
+- [ ] Batch tag update
+
+### Collections Panel
+- [ ] Collection list
+- [ ] Execute query button
+- [ ] Create dynamic collection form
+- [ ] Edit collection name/description
+
+### Query Builder
+- [ ] Simple query input
+- [ ] Expression syntax help
+- [ ] Example queries
+- [ ] Save as collection option
+
+### Sync Status
+- [ ] Last sync timestamp
+- [ ] Pending changes count
+- [ ] Sync indicator icon
+- [ ] Manual sync trigger
+
+### Settings Modal
+- [ ] Server URL input
+- [ ] API Key input (show/hide)
+- [ ] Collection name input
+- [ ] Sync mode dropdown
+- [ ] Deletions checkbox
+- [ ] Auto-sync toggle
+- [ ] Test connection button
+
+## Phase 6: Error Handling
+
+### API Errors
+- [ ] Handle 401 (unauthorized)
+- [ ] Handle 403 (forbidden)
+- [ ] Handle 429 (rate limited)
+- [ ] Handle 500 (server error)
+- [ ] Show user-friendly messages
+
+### Network Errors
+- [ ] Offline detection
+- [ ] Queue changes offline
+- [ ] Retry on reconnection
+- [ ] Sync when back online
+
+### UI Errors
+- [ ] Form validation
+- [ ] Input sanitization
+- [ ] Graceful fallback on errors
+- [ ] Error logging
+
+## Phase 7: Testing
+
+### Unit Tests
+- [ ] Test sync modes
+- [ ] Test conflict detection
+- [ ] Test query parsing
+- [ ] Test storage operations
+- [ ] Test bookmark manipulation
+
+### Integration Tests
+- [ ] Test API calls
+- [ ] Test background worker
+- [ ] Test popup communication
+- [ ] Test end-to-end sync flow
+
+### Manual Testing
+- [ ] Add bookmarks
+- [ ] Edit bookmarks
+- [ ] Delete bookmarks
+- [ ] Create collections
+- [ ] Execute queries
+- [ ] Test all sync modes
+- [ ] Test conflict resolution
+- [ ] Test offline scenarios
+
+## Phase 8: Packaging
+
+### Distribution
+- [ ] Create .zip distribution file
+- [ ] Verify manifest.json
+- [ ] Verify all assets
+- [ ] Test in fresh Firefox install
+
+### Version Management
+- [ ] Update version in manifest
+- [ ] Changelog file
+- [ ] Release notes
+
+## Phase 9: Documentation
+
+- [ ] API reference
+- [ ] User guide
+- [ ] Troubleshooting guide
+- [ ] Query syntax reference
+- [ ] FAQ
+
+## Future Enhancements
+
+- [ ] Background sync notifications
+- [ ] Auto-sync scheduler
+- [ ] Keyboard shortcuts
+- [ ] Gesture controls
+- [ ] Mobile companion app
+- [ ] Dark theme toggle
+- [ ] Custom colors