diff --git a/README.md b/README.md index 8e94b83..36243c0 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ > Professional Qt-based desktop application for intelligent drag-and-drop file handling between web applications and desktop clients (InDesign, Word, Notepad++, etc.) -![Status](https://img.shields.io/badge/Status-Development-yellow) ![License](https://img.shields.io/badge/License-MIT-blue) ![Python](https://img.shields.io/badge/Python-3.10%2B-blue) +![Status](https://img.shields.io/badge/Status-Pre--Release%20Phase%204-blue) ![License](https://img.shields.io/badge/License-MIT-blue) ![Python](https://img.shields.io/badge/Python-3.10%2B-blue) ## Overview @@ -23,16 +23,20 @@ WebDrop Bridge embeds a web application in a Qt container with full filesystem a - ✅ **Embedded Web App** - QtWebEngine provides Chromium without browser limitations - ✅ **Drag Interception** - Converts text paths to native file operations - ✅ **Path Whitelist** - Security-conscious file system access control +- ✅ **Configuration Management** - Profile-based settings with validation +- ✅ **Settings Dialog** - Professional UI for path, URL, logging, and window configuration +- ✅ **Auto-Update System** - Automatic release detection via Forgejo API - ✅ **Professional Build Pipeline** - MSI for Windows, DMG for macOS -- ✅ **Comprehensive Testing** - Unit, integration, and end-to-end tests +- ✅ **Comprehensive Testing** - Unit, integration, and end-to-end tests (80%+ coverage) - ✅ **CI/CD Ready** - GitHub Actions workflows included +- ✅ **Structured Logging** - File-based logging with configurable levels ## Quick Start ### Requirements - Python 3.10+ - Windows 10/11 or macOS 12+ -- 100 MB disk space +- 200 MB disk space (includes Chromium from PyInstaller) ### Installation from Source @@ -41,10 +45,11 @@ WebDrop Bridge embeds a web application in a Qt container with full filesystem a git clone https://github.com/yourusername/webdrop-bridge.git cd webdrop-bridge -# Create virtual environment +# Create and activate virtual environment python -m venv venv -source venv/bin/activate # macOS/Linux -# venv\Scripts\activate # Windows +source venv/bin/activate # macOS/Linux +# venv\Scripts\activate.ps1 # Windows (PowerShell) +# venv\Scripts\activate.bat # Windows (cmd.exe) # Install dependencies pip install -r requirements.txt @@ -60,14 +65,14 @@ python -m webdrop_bridge.main pip install -r requirements-dev.txt # Run tests -pytest +pytest tests -v -# Run linting checks -tox -e lint +# Run all quality checks (lint, type, format) +tox -# Build for your platform -tox -e build-windows # Windows -tox -e build-macos # macOS +# Build installers +python build/scripts/build_windows.py # Windows MSI +bash build/scripts/build_macos.sh # macOS DMG ``` ## Project Structure @@ -130,29 +135,86 @@ webdrop-bridge/ ## Configuration -Create `.env` file from `.env.example`: +WebDrop Bridge supports two configuration methods: + +### 1. Settings Dialog (Recommended) +Launch the application and access the Settings menu to configure: +- **Paths Tab** - Add/remove allowed root directories +- **URLs Tab** - Configure allowed web URLs (whitelist mode) +- **Logging Tab** - Set log level and file location +- **Window Tab** - Configure window dimensions +- **Profiles Tab** - Save/load/export-import configuration profiles + +Profiles are saved in `~/.webdrop-bridge/profiles/` + +### 2. Environment Variables +Create a `.env` file in the project root. Available settings: ```bash -cp .env.example .env -``` +# Application +APP_NAME=WebDrop Bridge +APP_VERSION=1.0.0 -Key settings: -- `WEBAPP_URL` - Local or remote web app URL -- `ALLOWED_ROOTS` - Comma-separated whitelist of allowed directories -- `LOG_LEVEL` - DEBUG, INFO, WARNING, ERROR -- `WINDOW_WIDTH` / `WINDOW_HEIGHT` - Initial window size +# Paths (comma-separated) +ALLOWED_ROOTS=Z:/,C:/Users/Public + +# Web URLs (empty = no restriction, items = kiosk mode) +ALLOWED_URLS= + +# Interface +WEBAPP_URL=file:///./webapp/index.html +WINDOW_WIDTH=1024 +WINDOW_HEIGHT=768 + +# Logging +LOG_LEVEL=INFO +ENABLE_LOGGING=true +``` ## Testing -- Unit tests: `pytest tests/unit/ -v` -- Integration tests: `pytest tests/integration/ -v` -- Coverage: `pytest --cov=src/webdrop_bridge` +WebDrop Bridge includes comprehensive test coverage with unit, integration, and end-to-end tests. -Integration tests for the update workflow are in [tests/integration/test_update_flow.py](tests/integration/test_update_flow.py). +```bash +# Run all tests +pytest tests -v + +# Run with coverage report +pytest tests --cov=src/webdrop_bridge --cov-report=html + +# Run specific test categories +pytest tests/unit -v # Unit tests only +pytest tests/integration -v # Integration tests only + +# Run specific test +pytest tests/unit/test_validator.py -v + +# Run tests matching a pattern +pytest tests -k "config" -v +``` + +**Test Coverage**: +- Current target: 80%+ +- Coverage report: `htmlcov/index.html` + +Integration tests cover: +- Drag-and-drop workflow +- Update flow and release detection +- End-to-end application scenarios ## Auto-Update System -WebDrop Bridge supports automatic updates via the Forgejo Releases API. See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for technical details. +WebDrop Bridge includes an intelligent auto-update system that: + +- **Automatic Detection**: Periodically checks Forgejo/GitHub releases API +- **Smart Caching**: Avoids redundant network calls with smart caching +- **User Notification**: Alerts users of available updates via UI +- **Release Notes**: Displays release notes and changes +- **Safe Deployment**: Only triggers on newer versions + +The update system is fully integrated with the application and runs in the background without blocking the UI. + +For technical details, see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md#update-system). ## Changelog @@ -160,23 +222,52 @@ See [CHANGELOG.md](CHANGELOG.md) for release notes. ## Building Installers -### Windows MSI +### Windows MSI Installer ```bash -pip install pyinstaller +# Simple build (creates standalone .exe) python build/scripts/build_windows.py + +# Build with MSI installer +python build/scripts/build_windows.py --msi + +# Build and sign executable +python build/scripts/build_windows.py --sign ``` -Output: `build/dist/WebDropBridge.exe` +Output: +- Standalone executable: `build/dist/windows/WebDropBridge.exe` (~195 MB) +- Optional MSI installer: `build/dist/windows/WebDropBridge.msi` +- SHA256 checksum: `build/dist/windows/WebDropBridge.exe.sha256` -### macOS DMG +### macOS DMG Installer ```bash -pip install pyinstaller +# Build DMG (requires macOS) bash build/scripts/build_macos.sh + +# Build with code signing +SIGN_APP=true bash build/scripts/build_macos.sh + +# Build with notarization +NOTARIZE_APP=true bash build/scripts/build_macos.sh ``` -Output: `build/dist/WebDropBridge.dmg` +Output: +- DMG installer: `build/dist/macos/WebDropBridge.dmg` +- App bundle: `build/dist/macos/WebDropBridge.app` + +### Creating Releases + +For Forgejo/GitHub releases: + +```bash +# Windows - Create release with executable +powershell -ExecutionPolicy Bypass -File build/scripts/create_release.ps1 + +# macOS - Create release with DMG +bash build/scripts/create_release.sh +``` ## Development Workflow @@ -249,13 +340,35 @@ MIT License - see [LICENSE](LICENSE) file for details - Inspired by professional desktop integration practices - Special thanks to the Qt community +## Development Status + +**Current Phase**: Phase 4.3 - Advanced Configuration & Testing + +**Completed**: +- ✅ Phase 1: Core Components (Validator, Config, Drag Interceptor, Main Window) +- ✅ Phase 2: UI Implementation (Settings Dialog, Main Window UI Components) +- ✅ Phase 3: Build & Distribution (Windows MSI, macOS DMG, Release Scripts) +- ✅ Phase 4.1: Update System (Auto-update, Forgejo API integration) +- ✅ Phase 4.2: Web App Improvements (Modern UI, Drag-drop testing) +- ✅ Phase 4.3: Advanced Configuration (Profiles, Validation, Settings UI) + +**In Progress/Planned**: +- Phase 4.4: Performance optimization & security hardening +- Phase 5: Release candidates & final testing +- v1.0: Stable Windows & macOS release + ## Roadmap -- [ ] v1.0 - Stable Windows & macOS release -- [ ] v1.1 - Advanced filtering and logging UI +- [x] Core drag-drop functionality +- [x] Configuration management with profiles +- [x] Auto-update system +- [x] Professional build pipeline +- [x] Comprehensive test suite +- [ ] Performance benchmarking & optimization +- [ ] Security audit & hardening +- [ ] v1.1 - Advanced filtering and extended logging - [ ] v1.2 - API for custom handlers - [ ] v2.0 - Plugin architecture -- [ ] v2.1 - Cloud storage integration (OneDrive, Google Drive) ## Support @@ -265,4 +378,4 @@ MIT License - see [LICENSE](LICENSE) file for details --- -**Status**: Alpha Development | **Last Updated**: January 2026 +**Development Phase**: Pre-Release Phase 4.3 | **Last Updated**: February 2026 | **Python**: 3.10+ | **Qt**: PySide6 (Qt 6)