webdrop-bridge/.github/copilot-instructions.md

WebDrop Bridge - Project Guidelines for AI Assistants

Project Context

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 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/__init__.py	Package info, version (0.7.1)
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	Configuration validation, profiles, import/export
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/bridge_script_intercept.js	JavaScript drag interception and WebChannel bridge
src/webdrop_bridge/ui/download_interceptor.js	Download handling for web content
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 (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

"""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.

    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 - currently Phase 4 Complete, Phase 5 in planning
2. Understand the architecture: Read 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 (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

# Setup (one-time)
pip install -r requirements-dev.txt

# 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 (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 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

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)

Update Flow

• UpdateManager checks for new releases via Forgejo API.
• Caching is used to avoid redundant network calls.
• Only newer versions trigger update signals.
• Release notes and assets are parsed and preserved.

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

# 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_update_flow.py

# Fixtures: Reusable test data
tests/conftest.py
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 (Google-style format)
• Modules: Add docstring at top of file
• Classes: Document purpose, attributes, and usage in docstring
• Functions: Document args, returns, raises, and examples
• Features: Update DEVELOPMENT_PLAN.md milestones
• Architecture changes: Update docs/ARCHITECTURE.md
• Config changes: Update CONFIG_README.md
• Breaking changes: Update CHANGELOG.md and DEVELOPMENT_PLAN.md
• Code examples: Preferred format is in docstrings with >>> syntax

Git Workflow

# 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 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 (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 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 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, 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: Phase 4 Complete - Phase 5 (Release Candidates) In Progress Version: 0.7.1 Last Updated: March 3, 2026