Add initial project structure and documentation
- Created architecture documentation outlining high-level design, module organization, data flow, security model, performance considerations, testing strategy, and deployment architecture. - Added pyproject.toml for project metadata and dependencies management. - Introduced requirements files for development and production dependencies. - Set up testing configuration with pytest and tox. - Established basic directory structure for source code and tests, including __init__.py files. - Implemented a sample web application (index.html) for drag-and-drop functionality. - Configured VS Code workspace settings for Python development.
This commit is contained in:
commit
61aa33633c
34 changed files with 5342 additions and 0 deletions
187
.github/copilot-instructions.md
vendored
Normal file
187
.github/copilot-instructions.md
vendored
Normal file
|
|
@ -0,0 +1,187 @@
|
|||
# WebDrop Bridge - Project Guidelines for AI Assistants
|
||||
|
||||
## Project Context
|
||||
|
||||
WebDrop Bridge is a professional Qt-based desktop application that converts web-based drag-and-drop text paths into native file operations. It's designed for production deployment on Windows and macOS with professional-grade testing, documentation, and CI/CD.
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
- **Framework**: PySide6 (Qt bindings for Python)
|
||||
- **Structure**: Modular (core/, ui/, utils/)
|
||||
- **Testing**: pytest with unit, integration, and fixture-based tests
|
||||
- **Distribution**: PyInstaller → MSI (Windows), DMG (macOS)
|
||||
|
||||
## Key Files & Their Purpose
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `src/webdrop_bridge/main.py` | Application entry point |
|
||||
| `src/webdrop_bridge/config.py` | Configuration management |
|
||||
| `src/webdrop_bridge/core/validator.py` | Path validation and security |
|
||||
| `src/webdrop_bridge/core/drag_interceptor.py` | Drag-and-drop handling |
|
||||
| `src/webdrop_bridge/ui/main_window.py` | Main Qt window |
|
||||
| `tests/` | Pytest-based test suite |
|
||||
| `pyproject.toml` | Modern Python packaging |
|
||||
| `tox.ini` | Test automation config |
|
||||
|
||||
## Code Standards
|
||||
|
||||
### Python Style
|
||||
- **Formatter**: Black (100 character line length)
|
||||
- **Linter**: Ruff
|
||||
- **Type Hints**: Required for all public APIs
|
||||
- **Docstrings**: Google-style format
|
||||
|
||||
### Example
|
||||
```python
|
||||
def validate_path(path: Path, allowed_roots: List[Path]) -> bool:
|
||||
"""Validate path against allowed roots.
|
||||
|
||||
Args:
|
||||
path: File path to validate
|
||||
allowed_roots: List of allowed root directories
|
||||
|
||||
Returns:
|
||||
True if path is valid, False otherwise
|
||||
"""
|
||||
pass
|
||||
```
|
||||
|
||||
## Before Making Changes
|
||||
|
||||
1. **Check the development plan**: See `DEVELOPMENT_PLAN.md` for current phase and priorities
|
||||
2. **Understand the architecture**: Read `docs/ARCHITECTURE.md`
|
||||
3. **Follow the structure**: Keep code organized in appropriate modules (core/, ui/, utils/)
|
||||
4. **Write tests first**: Use TDD approach - write tests before implementing
|
||||
|
||||
## Making Changes
|
||||
|
||||
1. **Run existing tests first**: `pytest tests -v`
|
||||
2. **Create test file**: `tests/unit/test_*.py`
|
||||
3. **Write failing test**: Verify it fails before implementing
|
||||
4. **Implement feature**: Follow code standards above
|
||||
5. **Run tests**: `pytest tests -v --cov`
|
||||
6. **Run quality checks**: `tox -e lint,type`
|
||||
7. **Update docs**: Add docstrings and update README if needed
|
||||
|
||||
## Common Commands
|
||||
|
||||
```bash
|
||||
# Setup
|
||||
pip install -r requirements-dev.txt
|
||||
|
||||
# Testing
|
||||
pytest tests -v
|
||||
pytest tests --cov=src/webdrop_bridge --cov-report=html
|
||||
|
||||
# Quality
|
||||
tox -e lint # Ruff + Black checks
|
||||
tox -e type # mypy type checking
|
||||
tox -e format # Auto-format code
|
||||
tox # All checks
|
||||
|
||||
# Building
|
||||
python build/scripts/build_windows.py # Windows
|
||||
bash build/scripts/build_macos.sh # macOS
|
||||
```
|
||||
|
||||
## Important Decisions
|
||||
|
||||
### Path Validation
|
||||
- Whitelist-based: Only allow configured root directories
|
||||
- All paths resolved to absolute before checking
|
||||
- Files must exist and be regular files
|
||||
|
||||
### Web Engine Security
|
||||
- `LocalContentCanAccessFileUrls`: True (required for drag)
|
||||
- `LocalContentCanAccessRemoteUrls`: False (prevent phishing)
|
||||
|
||||
### Cross-Platform
|
||||
- Use PySide6 APIs that work on both Windows and macOS
|
||||
- Test on both platforms when possible
|
||||
- Mark platform-specific tests with `@pytest.mark.windows` or `@pytest.mark.macos`
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
```python
|
||||
# Unit tests: Isolated component testing
|
||||
tests/unit/test_validator.py
|
||||
tests/unit/test_drag_interceptor.py
|
||||
|
||||
# Integration tests: Component interaction
|
||||
tests/integration/test_drag_workflow.py
|
||||
tests/integration/test_end_to_end.py
|
||||
|
||||
# Fixtures: Reusable test data
|
||||
tests/conftest.py
|
||||
tests/fixtures/
|
||||
```
|
||||
|
||||
Target: 80%+ code coverage
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
- Drag event handling: < 50ms total
|
||||
- Application startup: < 1 second
|
||||
- Memory baseline: < 200MB
|
||||
|
||||
## Documentation Requirements
|
||||
|
||||
- **Public APIs**: Docstrings required
|
||||
- **Modules**: Add docstring at top of file
|
||||
- **Features**: Update README.md and docs/
|
||||
- **Breaking changes**: Update DEVELOPMENT_PLAN.md
|
||||
|
||||
## Git Workflow
|
||||
|
||||
```bash
|
||||
# Create feature branch
|
||||
git checkout -b feature/my-feature
|
||||
|
||||
# Commit message format
|
||||
git commit -m "feat: add feature description
|
||||
|
||||
- Detailed explanation
|
||||
- Bullet points for changes"
|
||||
|
||||
# Push to fork and create PR
|
||||
git push origin feature/my-feature
|
||||
```
|
||||
|
||||
## Review Checklist
|
||||
|
||||
- [ ] Tests pass (100% on CI)
|
||||
- [ ] Code follows black/ruff standards
|
||||
- [ ] Type hints added for public APIs
|
||||
- [ ] Documentation updated
|
||||
- [ ] No security concerns
|
||||
- [ ] Cross-platform compatibility verified (if applicable)
|
||||
|
||||
## When You're Stuck
|
||||
|
||||
1. **Check DEVELOPMENT_PLAN.md**: Current phase and architecture decisions
|
||||
2. **Look at tests**: Existing tests show expected behavior
|
||||
3. **Read docstrings**: Functions document their contracts
|
||||
4. **Check docs/ARCHITECTURE.md**: Design patterns and data flow
|
||||
|
||||
## What NOT to Do
|
||||
|
||||
❌ Change architecture without discussion
|
||||
❌ Add dependencies without updating pyproject.toml
|
||||
❌ Merge without tests passing
|
||||
❌ Remove type hints or docstrings
|
||||
❌ Commit without running `tox -e lint,type`
|
||||
❌ Add platform-specific code without tests
|
||||
|
||||
## Notes for Modifications
|
||||
|
||||
- This is a production-quality application, not a PoC
|
||||
- Code quality and testing are non-negotiable
|
||||
- Cross-platform support (Windows + macOS) is required
|
||||
- User security (path validation) is critical
|
||||
- Documentation must keep pace with code
|
||||
|
||||
---
|
||||
|
||||
**Current Status**: Pre-release development (Phase 1-2)
|
||||
**Last Updated**: January 2026
|
||||
Loading…
Add table
Add a link
Reference in a new issue