myworkspace/LinkSyncExtension/tasks.md

# 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