HIM-public/webdrop-bridge
HIM-public/webdrop-bridge
5
0
Fork 0
Code Issues 3 Pull requests Projects 1 Releases 1 Packages Wiki Activity Actions

docs: Update copilot instructions to reflect Phase 4 completion and Phase 5 planning

Browse source
This commit is contained in:
claudi 2026-02-18 12:31:52 +01:00
parent 4011f46ab7
commit a4d735d759
1 changed files with 122 additions and 65 deletions
Download patch file Download diff file Expand all files Collapse all files

185
.github/copilot-instructions.md vendored
View file

@ -2,39 +2,57 @@
## Project Context ## 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. WebDrop Bridge is a professional Qt-based desktop application (v0.5.0) 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.
**Current Status**: Phase 4 Complete - Phase 5 (Release Candidates) Planned as of Feb 18, 2026
## Architecture Overview ## Architecture Overview
- **Framework**: PySide6 (Qt bindings for Python) - **Framework**: PySide6 (Qt bindings for Python)
- **Python**: 3.9+ (tested on 3.10, 3.11, 3.12, 3.13, 3.14)
- **Structure**: Modular (core/, ui/, utils/) - **Structure**: Modular (core/, ui/, utils/)
- **Testing**: pytest with unit, integration, and fixture-based tests - **Testing**: pytest with unit and integration tests
- **Distribution**: PyInstaller → MSI (Windows), DMG (macOS) - **Distribution**: PyInstaller → MSI (Windows), DMG (macOS)
- **Web Integration**: QWebEngineView with security-hardened JavaScript bridge
## Key Files & Their Purpose ## Key Files & Their Purpose
| File | Purpose | | File | Purpose |
|------|---------| |------|---------|
| `src/webdrop_bridge/main.py` | Application entry point | | `src/webdrop_bridge/__init__.py` | Package info, version (0.5.0) |
| `src/webdrop_bridge/config.py` | Configuration management | | `src/webdrop_bridge/main.py` | Application entry point, config loading |
| `src/webdrop_bridge/core/validator.py` | Path validation and security | | `src/webdrop_bridge/config.py` | Configuration management (file/env), URL mappings, validation |
| `src/webdrop_bridge/core/drag_interceptor.py` | Drag-and-drop handling | | `src/webdrop_bridge/core/validator.py` | Path validation against whitelist, security checks |
| `src/webdrop_bridge/core/updater.py` | Update check and release management | | `src/webdrop_bridge/core/drag_interceptor.py` | Drag-and-drop event handling |
| `src/webdrop_bridge/ui/main_window.py` | Main Qt window | | `src/webdrop_bridge/core/config_manager.py` | File-based config loading and caching |
| `tests/` | Pytest-based test suite | | `src/webdrop_bridge/core/url_converter.py` | Azure blob URL → local path conversion |
| `pyproject.toml` | Modern Python packaging | | `src/webdrop_bridge/core/updater.py` | Update checking via Forgejo API, release management |
| `tox.ini` | Test automation config | | `src/webdrop_bridge/ui/main_window.py` | Main Qt window, config injection, menu bar |
| `src/webdrop_bridge/ui/restricted_web_view.py` | Hardened QWebEngineView with security policies |
| `src/webdrop_bridge/ui/settings_dialog.py` | Settings UI, URL mapping configuration |
| `src/webdrop_bridge/ui/update_manager_ui.py` | Update check UI and dialogs |
| `src/webdrop_bridge/utils/logging.py` | Logging configuration (console + file) |
| `tests/` | pytest-based test suite (unit/ and integration/) |
| `pyproject.toml` | Modern Python packaging and tool config |
| `tox.ini` | Test automation (pytest, lint, type, format) |
## Code Standards ## Code Standards
### Python Style ### Python Style
- **Formatter**: Black (100 character line length) - **Formatter**: Black (88 character line length)
- **Linter**: Ruff - **Import Sorter**: isort (black-compatible profile)
- **Type Hints**: Required for all public APIs - **Linter**: Ruff (checks style, security, complexity)
- **Docstrings**: Google-style format - **Type Checker**: mypy (strict mode for core modules)
- **Type Hints**: Required for all public APIs and core modules
- **Docstrings**: Google-style format (module, class, function level)
### Example ### Example
```python ```python
"""Module for path validation."""
from pathlib import Path
from typing import List
def validate_path(path: Path, allowed_roots: List[Path]) -> bool: def validate_path(path: Path, allowed_roots: List[Path]) -> bool:
"""Validate path against allowed roots. """Validate path against allowed roots.
@ -50,26 +68,35 @@ def validate_path(path: Path, allowed_roots: List[Path]) -> bool:
## Before Making Changes ## Before Making Changes
1. **Check the development plan**: See `DEVELOPMENT_PLAN.md` for current phase and priorities 1. **Check the development plan**: See [DEVELOPMENT_PLAN.md](../../DEVELOPMENT_PLAN.md) - currently Phase 4 Complete, Phase 5 in planning
2. **Understand the architecture**: Read `docs/ARCHITECTURE.md` 2. **Understand the architecture**: Read [docs/ARCHITECTURE.md](../../docs/ARCHITECTURE.md)
3. **Follow the structure**: Keep code organized in appropriate modules (core/, ui/, utils/) 3. **Review actual implementation**: Look at existing modules in core/, ui/, utils/
4. **Write tests first**: Use TDD approach - write tests before implementing 4. **Follow the structure**: Keep code organized in appropriate modules
5. **Write tests**: Use pytest - write tests for new functionality
## Making Changes ## Making Changes
1. **Run existing tests first**: `pytest tests -v` 1. **Run existing tests first**: `pytest tests -v` (should pass)
2. **Create test file**: `tests/unit/test_*.py` 2. **Create test file**: `tests/unit/test_*.py` or `tests/integration/test_*.py`
3. **Write failing test**: Verify it fails before implementing 3. **Write test**: Verify test executes (may fail if feature incomplete)
4. **Implement feature**: Follow code standards above 4. **Implement feature**: Follow code standards (black, ruff, isort, mypy)
5. **Run tests**: `pytest tests -v --cov` 5. **Format code**: `tox -e format` (auto-formats with black/isort)
6. **Run quality checks**: `tox -e lint,type` 6. **Run all checks**: `tox -e lint,type` (ruff, mypy validation)
7. **Update docs**: Add docstrings and update README if needed 7. **Run tests with coverage**: `pytest tests --cov=src/webdrop_bridge`
8. **Update docs**: Add/update docstrings, README if needed
## Development Environment ## Development Environment
**Virtual Environment**: `.venv` (already created) **Virtual Environment**: `.venv` (already created)
- Activate: `.venv\Scripts\activate` (Windows) or `source .venv/bin/activate` (macOS/Linux) - Activate: `.venv\Scripts\activate` (Windows) or `source .venv/bin/activate` (macOS/Linux)
- All Python commands automatically use this environment through VS Code integration - All Python commands automatically use this environment through VS Code integration
- **Note**: Only activate if running commands outside VS Code terminal
**Required**:
- Python 3.9+ (tested on 3.10, 3.11, 3.12, 3.13, 3.14)
- PySide6 (for Qt GUI)
- pytest (for testing)
- tox (for automated testing and quality checks)
## Common Commands ## Common Commands
@ -77,19 +104,25 @@ def validate_path(path: Path, allowed_roots: List[Path]) -> bool:
# Setup (one-time) # Setup (one-time)
pip install -r requirements-dev.txt pip install -r requirements-dev.txt
# Testing (uses .venv automatically) # Testing
pytest tests -v pytest tests -v # Run all tests
pytest tests --cov=src/webdrop_bridge --cov-report=html pytest tests --cov=src/webdrop_bridge # With coverage
pytest tests::test_module -v # Specific test
pytest -k test_validator # By name pattern
# Quality checks # Quality checks (these use tox environments)
tox -e lint # Ruff + Black checks tox -e lint # Ruff + Black check + isort check
tox -e format # Auto-format (Black + isort)
tox -e type # mypy type checking tox -e type # mypy type checking
tox -e format # Auto-format code tox -e coverage # Tests with coverage report
tox # All checks tox # Run everything
# Building # Building distributions
python build/scripts/build_windows.py # Windows python build/scripts/build_windows.py # Windows (requires pyinstaller, wix)
bash build/scripts/build_macos.sh # macOS bash build/scripts/build_macos.sh # macOS (requires pyinstaller, notarization key)
# Running application
python -m webdrop_bridge.main # Start application
``` ```
## Important Decisions ## Important Decisions
@ -120,10 +153,17 @@ bash build/scripts/build_macos.sh # macOS
# Unit tests: Isolated component testing # Unit tests: Isolated component testing
tests/unit/test_validator.py tests/unit/test_validator.py
tests/unit/test_drag_interceptor.py tests/unit/test_drag_interceptor.py
tests/unit/test_url_converter.py
tests/unit/test_config.py
tests/unit/test_config_manager.py
tests/unit/test_logging.py
tests/unit/test_updater.py
tests/unit/test_main_window.py
tests/unit/test_restricted_web_view.py
tests/unit/test_settings_dialog.py
tests/unit/test_update_manager_ui.py
# Integration tests: Component interaction and update flow # Integration tests: Component interaction and update flow
tests/integration/test_drag_workflow.py
tests/integration/test_end_to_end.py
tests/integration/test_update_flow.py tests/integration/test_update_flow.py
# Fixtures: Reusable test data # Fixtures: Reusable test data
@ -132,20 +172,27 @@ tests/fixtures/
``` ```
Target: 80%+ code coverage Target: 80%+ code coverage
- Use `pytest --cov=src/webdrop_bridge --cov-report=html` to generate coverage reports
- Review htmlcov/index.html for detailed coverage breakdown
## Performance Considerations ## Performance Considerations
- Drag event handling: < 50ms total - Drag event handling: < 50ms total
- Application startup: < 1 second - Application startup: < 1 second
- Memory baseline: < 200MB - Memory baseline: < 200MB
- Logging overhead: minimize file I/O in drag operations
## Documentation Requirements ## Documentation Requirements
- **Public APIs**: Docstrings required - **Public APIs**: Docstrings required (Google-style format)
- **Modules**: Add docstring at top of file - **Modules**: Add docstring at top of file
- **Features**: Update README.md and docs/ - **Classes**: Document purpose, attributes, and usage in docstring
- **Integration tests**: Reference and document in README.md and docs/ARCHITECTURE.md - **Functions**: Document args, returns, raises, and examples
- **Breaking changes**: Update DEVELOPMENT_PLAN.md - **Features**: Update [DEVELOPMENT_PLAN.md](../../DEVELOPMENT_PLAN.md) milestones
- **Architecture changes**: Update [docs/ARCHITECTURE.md](../../docs/ARCHITECTURE.md)
- **Config changes**: Update [CONFIG_README.md](../../CONFIG_README.md)
- **Breaking changes**: Update CHANGELOG.md and DEVELOPMENT_PLAN.md
- **Code examples**: Preferred format is in docstrings with >>> syntax
## Git Workflow ## Git Workflow
@ -165,38 +212,48 @@ git push origin feature/my-feature
## Review Checklist ## Review Checklist
- [ ] Tests pass (100% on CI) - [ ] Tests pass (100% on local runs, `pytest tests -v`)
- [ ] Code follows black/ruff standards - [ ] Code formatted with black/isort (`tox -e format`)
- [ ] Type hints added for public APIs - [ ] All linting passes (`tox -e lint`)
- [ ] Documentation updated - [ ] Type hints complete (`tox -e type` passes)
- [ ] No security concerns - [ ] Docstrings added for all public APIs
- [ ] Cross-platform compatibility verified (if applicable) - [ ] No security concerns (especially in path validation)
- [ ] Cross-platform compatibility verified (Windows + macOS tests if applicable)
- [ ] Configuration handling tested for edge cases
- [ ] Git history clean (meaningful commits with proper messages)
## When You're Stuck ## When You're Stuck
1. **Check DEVELOPMENT_PLAN.md**: Current phase and architecture decisions 1. **Check DEVELOPMENT_PLAN.md**: Current phase (Phase 4 Complete) and architecture decisions
2. **Look at tests**: Existing tests show expected behavior 2. **Look at tests**: Existing tests in `tests/unit/` and `tests/integration/` show expected behavior
3. **Read docstrings**: Functions document their contracts 3. **Read docstrings**: Functions document their contracts using Google-style format
4. **Check docs/ARCHITECTURE.md**: Design patterns and data flow 4. **Check docs/ARCHITECTURE.md**: Design patterns, data flow, and module organization
5. **Review config examples**: See [CONFIG_README.md](../../CONFIG_README.md) and `config.example.json`
6. **Check CI output**: Look at tox and pytest output for detailed error messages
## What NOT to Do ## What NOT to Do
❌ Change architecture without discussion ❌ Change architecture without reviewing DEVELOPMENT_PLAN.md first
❌ Add dependencies without updating pyproject.toml ❌ Add dependencies without updating requirements-dev.txt and pyproject.toml
❌ Merge without tests passing ❌ Commit without running `tox -e format,lint,type`
❌ Remove type hints or docstrings ❌ Remove type hints or docstrings from public APIs
❌ Commit without running `tox -e lint,type` ❌ Add imports without running `tox -e format` (isort cleanup)
❌ Add platform-specific code without tests ❌ Add platform-specific code without tests marked with @pytest.mark.windows or @pytest.mark.macos
❌ Modify path validation logic without security review
❌ Force-push to main or release branches
## Notes for Modifications ## Notes for Modifications
- This is a production-quality application, not a PoC - This is a production-quality application, not a PoC
- Code quality and testing are non-negotiable - Code quality, testing, and documentation are non-negotiable
- Cross-platform support (Windows + macOS) is required - Cross-platform support (Windows + macOS) is required and tested
- User security (path validation) is critical - User security (path validation) is critical - be extra careful with path operations
- Documentation must keep pace with code - Configuration must support both .env files and JSON files
- All error messages should be meaningful and logged appropriately
- Documentation must keep pace with code changes
--- ---
**Current Status**: Pre-release development (Phase 1-2) **Current Status**: Phase 4 Complete (Jan 29, 2026) - Phase 5 (Release Candidates) Planned
**Last Updated**: January 2026 **Version**: 0.5.0
**Last Updated**: February 18, 2026