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

LinkSyncServer/AGENTS.md

@@ -0,0 +1,113 @@
+# AGENTS.md - LinkSyncServer
+
+## Project Overview
+
+LinkSyncServer is a self-hosted bookmark server with advanced collection and query capabilities. It provides a RESTful API and web interface for managing bookmarks (links), collections (static or dynamic sets), and supports synchronization with browser extensions.
+
+## Setup & Build Commands
+
+- **Build**: `docker-compose up -d --build`
+- **Test**: `pytest tests/ -v`
+- **Lint**: `ruff check .` && `mypy app.py models/`
+- **Dev**: `docker-compose up web`
+- **Migrate**: `alembic upgrade head`
+
+## Architecture Notes
+
+### Core Components
+
+1. **Authentication Layer**: JWT-based auth with admin/regular user roles
+2. **Link Management**: CRUD for links with all Firefox bookmark fields
+3. **Collection Engine**: Static and dynamic collections with query support
+4. **Query Parser**: Expression parser supporting AND/OR/XOR set operations
+5. **Sync Protocol**: Extension sync endpoint with conflict resolution
+
+### Data Models
+
+- **User**: Authentication and authorization
+- **Link**: Bookmark with all Firefox fields
+- **Collection**: Static or dynamic set of links
+- **Tag**: Optional categorization
+- **AuditLog**: Track changes
+
+### Query Engine
+
+Query syntax: `('term1', 'term2') OR tagA AND tagB XOR url:example.com`
+
+- Precedence: `()` > XOR > AND > OR
+- Left-to-right evaluation otherwise
+- Full-text search via PostgreSQL tsvector
+
+## Testing Protocol
+
+- All tests must pass before committing
+- Run `pytest tests/ -v` for full test suite
+- Coverage target: >80%
+- E2E tests cover critical user flows
+
+## Conventions
+
+### File Naming
+
+- Models: `{entity}.py` in `models/` directory
+- Endpoints: `endpoints/{resource}.py`
+- Queries: `queries/{operation}.py`
+
+### Error Handling
+
+- Use HTTP status codes appropriately
+- Return structured error responses
+- Log errors with stack traces in debug mode
+
+### API Design
+
+- RESTful conventions
+- JSON responses with Content-Type
+- Paginated lists with limit/offset
+- OpenAPI documentation via `@openapi`
+
+### Database
+
+- UUID primary keys
+- Timestamps on all records
+- Foreign keys with cascade delete where appropriate
+- Full-text search indexes on searchable fields
+
+## Known Issues / Technical Debt
+
+- None at initialization
+- Query engine performance to be optimized
+- Caching layer to be implemented
+
+## Project-Specific Tools
+
+- **Query Parser**: `queries/parser.py`
+- **Query Executor**: `queries/executor.py`
+- **Sync Logic**: `api/endpoints/sync.py`
+
+## Related Files
+
+- `README.md` - Overview and quick start
+- `design.md` - Architecture and API details
+- `tasks.md` - Implementation checklist
+- `docker-compose.yml` - Deployment configuration
+
+## Admin User Creation
+
+Admin user is created from environment variables:
+- `ADMIN_USERNAME`
+- `ADMIN_PASSWORD`
+- `SECRET_KEY` (generate securely)
+
+Admin can create:
+- Regular users
+- Admin users
+- API keys
+- System settings
+
+## Security Notes
+
+- Never commit `.env` files
+- Use strong passwords
+- Rotate SECRET_KEY periodically
+- Enable HTTPS in production