# 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
```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.

    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](../../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` (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

```bash
# 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

```python
# 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](../../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

```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 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](../../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