From a4d735d759cfa8b164267aeabf93c072ef37d8c4 Mon Sep 17 00:00:00 2001 From: claudi Date: Wed, 18 Feb 2026 12:31:52 +0100 Subject: [PATCH] docs: Update copilot instructions to reflect Phase 4 completion and Phase 5 planning --- .github/copilot-instructions.md | 187 +++++++++++++++++++++----------- 1 file changed, 122 insertions(+), 65 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 9ff940c..7de0a71 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -2,39 +2,57 @@ ## 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 - **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/) -- **Testing**: pytest with unit, integration, and fixture-based tests +- **Testing**: pytest with unit and integration tests - **Distribution**: PyInstaller → MSI (Windows), DMG (macOS) +- **Web Integration**: QWebEngineView with security-hardened JavaScript bridge ## 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/core/updater.py` | Update check and release management | -| `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 | +| `src/webdrop_bridge/__init__.py` | Package info, version (0.5.0) | +| `src/webdrop_bridge/main.py` | Application entry point, config loading | +| `src/webdrop_bridge/config.py` | Configuration management (file/env), URL mappings, validation | +| `src/webdrop_bridge/core/validator.py` | Path validation against whitelist, security checks | +| `src/webdrop_bridge/core/drag_interceptor.py` | Drag-and-drop event handling | +| `src/webdrop_bridge/core/config_manager.py` | File-based config loading and caching | +| `src/webdrop_bridge/core/url_converter.py` | Azure blob URL → local path conversion | +| `src/webdrop_bridge/core/updater.py` | Update checking via Forgejo API, release management | +| `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 ### Python Style -- **Formatter**: Black (100 character line length) -- **Linter**: Ruff -- **Type Hints**: Required for all public APIs -- **Docstrings**: Google-style format +- **Formatter**: Black (88 character line length) +- **Import Sorter**: isort (black-compatible profile) +- **Linter**: Ruff (checks style, security, complexity) +- **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 ```python +"""Module for path validation.""" + +from pathlib import Path +from typing import List + def validate_path(path: Path, allowed_roots: List[Path]) -> bool: """Validate path against allowed roots. @@ -50,26 +68,35 @@ def validate_path(path: Path, allowed_roots: List[Path]) -> bool: ## 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 +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](../../docs/ARCHITECTURE.md) +3. **Review actual implementation**: Look at existing modules in core/, ui/, utils/ +4. **Follow the structure**: Keep code organized in appropriate modules +5. **Write tests**: Use pytest - write tests for new functionality ## 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 +1. **Run existing tests first**: `pytest tests -v` (should pass) +2. **Create test file**: `tests/unit/test_*.py` or `tests/integration/test_*.py` +3. **Write test**: Verify test executes (may fail if feature incomplete) +4. **Implement feature**: Follow code standards (black, ruff, isort, mypy) +5. **Format code**: `tox -e format` (auto-formats with black/isort) +6. **Run all checks**: `tox -e lint,type` (ruff, mypy validation) +7. **Run tests with coverage**: `pytest tests --cov=src/webdrop_bridge` +8. **Update docs**: Add/update docstrings, README if needed ## Development Environment **Virtual Environment**: `.venv` (already created) - Activate: `.venv\Scripts\activate` (Windows) or `source .venv/bin/activate` (macOS/Linux) - 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 @@ -77,19 +104,25 @@ def validate_path(path: Path, allowed_roots: List[Path]) -> bool: # Setup (one-time) pip install -r requirements-dev.txt -# Testing (uses .venv automatically) -pytest tests -v -pytest tests --cov=src/webdrop_bridge --cov-report=html +# Testing +pytest tests -v # Run all tests +pytest tests --cov=src/webdrop_bridge # With coverage +pytest tests::test_module -v # Specific test +pytest -k test_validator # By name pattern -# Quality checks -tox -e lint # Ruff + Black checks -tox -e type # mypy type checking -tox -e format # Auto-format code -tox # All checks +# Quality checks (these use tox environments) +tox -e lint # Ruff + Black check + isort check +tox -e format # Auto-format (Black + isort) +tox -e type # mypy type checking +tox -e coverage # Tests with coverage report +tox # Run everything -# Building -python build/scripts/build_windows.py # Windows -bash build/scripts/build_macos.sh # macOS +# Building distributions +python build/scripts/build_windows.py # Windows (requires pyinstaller, wix) +bash build/scripts/build_macos.sh # macOS (requires pyinstaller, notarization key) + +# Running application +python -m webdrop_bridge.main # Start application ``` ## Important Decisions @@ -120,10 +153,17 @@ bash build/scripts/build_macos.sh # macOS # Unit tests: Isolated component testing tests/unit/test_validator.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 -tests/integration/test_drag_workflow.py -tests/integration/test_end_to_end.py tests/integration/test_update_flow.py # Fixtures: Reusable test data @@ -132,20 +172,27 @@ tests/fixtures/ ``` 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 - Drag event handling: < 50ms total - Application startup: < 1 second - Memory baseline: < 200MB +- Logging overhead: minimize file I/O in drag operations ## Documentation Requirements -- **Public APIs**: Docstrings required +- **Public APIs**: Docstrings required (Google-style format) - **Modules**: Add docstring at top of file -- **Features**: Update README.md and docs/ -- **Integration tests**: Reference and document in README.md and docs/ARCHITECTURE.md -- **Breaking changes**: Update DEVELOPMENT_PLAN.md +- **Classes**: Document purpose, attributes, and usage in docstring +- **Functions**: Document args, returns, raises, and examples +- **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 @@ -165,38 +212,48 @@ 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) +- [ ] Tests pass (100% on local runs, `pytest tests -v`) +- [ ] Code formatted with black/isort (`tox -e format`) +- [ ] All linting passes (`tox -e lint`) +- [ ] Type hints complete (`tox -e type` passes) +- [ ] Docstrings added for all public APIs +- [ ] 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 -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 +1. **Check DEVELOPMENT_PLAN.md**: Current phase (Phase 4 Complete) and architecture decisions +2. **Look at tests**: Existing tests in `tests/unit/` and `tests/integration/` show expected behavior +3. **Read docstrings**: Functions document their contracts using Google-style format +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 -❌ 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 +❌ Change architecture without reviewing DEVELOPMENT_PLAN.md first +❌ Add dependencies without updating requirements-dev.txt and pyproject.toml +❌ Commit without running `tox -e format,lint,type` +❌ Remove type hints or docstrings from public APIs +❌ Add imports without running `tox -e format` (isort cleanup) +❌ 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 - 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 +- Code quality, testing, and documentation are non-negotiable +- Cross-platform support (Windows + macOS) is required and tested +- User security (path validation) is critical - be extra careful with path operations +- 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) -**Last Updated**: January 2026 +**Current Status**: Phase 4 Complete (Jan 29, 2026) - Phase 5 (Release Candidates) Planned +**Version**: 0.5.0 +**Last Updated**: February 18, 2026