myworkspace/LinkSyncExtension/tasks.md

LinkSyncExtension - Implementation Tasks

Phase 1: Project Setup

Setup Tasks

• Create project directory structure
• 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