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

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/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

Code Standards

Python Style

• Formatter: Black (100 character line length)
• Linter: Ruff
• Type Hints: Required for all public APIs
• Docstrings: Google-style format

Example

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

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

Common Commands

# 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

# Quality checks
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)

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

# 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
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/
• Integration tests: Reference and document in README.md and docs/ARCHITECTURE.md
• Breaking changes: Update DEVELOPMENT_PLAN.md

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