feat: Update README with status change, enhanced configuration details, and improved installation instructions
Some checks are pending
Tests & Quality Checks / Test on Python 3.11 (push) Waiting to run
Tests & Quality Checks / Test on Python 3.12 (push) Waiting to run
Tests & Quality Checks / Test on Python 3.11-1 (push) Waiting to run
Tests & Quality Checks / Test on Python 3.12-1 (push) Waiting to run
Tests & Quality Checks / Test on Python 3.10 (push) Waiting to run
Tests & Quality Checks / Test on Python 3.11-2 (push) Waiting to run
Tests & Quality Checks / Test on Python 3.12-2 (push) Waiting to run
Tests & Quality Checks / Build Artifacts (push) Blocked by required conditions
Tests & Quality Checks / Build Artifacts-1 (push) Blocked by required conditions

This commit is contained in:
claudi 2026-02-10 10:00:10 +01:00
parent 4ab44c83ba
commit c9704efc8d

183
README.md
View file

@ -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.) > 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 ## 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 - ✅ **Embedded Web App** - QtWebEngine provides Chromium without browser limitations
- ✅ **Drag Interception** - Converts text paths to native file operations - ✅ **Drag Interception** - Converts text paths to native file operations
- ✅ **Path Whitelist** - Security-conscious file system access control - ✅ **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 - ✅ **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 - ✅ **CI/CD Ready** - GitHub Actions workflows included
- ✅ **Structured Logging** - File-based logging with configurable levels
## Quick Start ## Quick Start
### Requirements ### Requirements
- Python 3.10+ - Python 3.10+
- Windows 10/11 or macOS 12+ - Windows 10/11 or macOS 12+
- 100 MB disk space - 200 MB disk space (includes Chromium from PyInstaller)
### Installation from Source ### 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 git clone https://github.com/yourusername/webdrop-bridge.git
cd webdrop-bridge cd webdrop-bridge
# Create virtual environment # Create and activate virtual environment
python -m venv venv python -m venv venv
source venv/bin/activate # macOS/Linux source venv/bin/activate # macOS/Linux
# venv\Scripts\activate # Windows # venv\Scripts\activate.ps1 # Windows (PowerShell)
# venv\Scripts\activate.bat # Windows (cmd.exe)
# Install dependencies # Install dependencies
pip install -r requirements.txt pip install -r requirements.txt
@ -60,14 +65,14 @@ python -m webdrop_bridge.main
pip install -r requirements-dev.txt pip install -r requirements-dev.txt
# Run tests # Run tests
pytest pytest tests -v
# Run linting checks # Run all quality checks (lint, type, format)
tox -e lint tox
# Build for your platform # Build installers
tox -e build-windows # Windows python build/scripts/build_windows.py # Windows MSI
tox -e build-macos # macOS bash build/scripts/build_macos.sh # macOS DMG
``` ```
## Project Structure ## Project Structure
@ -130,29 +135,86 @@ webdrop-bridge/
## Configuration ## 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 ```bash
cp .env.example .env # Application
``` APP_NAME=WebDrop Bridge
APP_VERSION=1.0.0
Key settings: # Paths (comma-separated)
- `WEBAPP_URL` - Local or remote web app URL ALLOWED_ROOTS=Z:/,C:/Users/Public
- `ALLOWED_ROOTS` - Comma-separated whitelist of allowed directories
- `LOG_LEVEL` - DEBUG, INFO, WARNING, ERROR # Web URLs (empty = no restriction, items = kiosk mode)
- `WINDOW_WIDTH` / `WINDOW_HEIGHT` - Initial window size ALLOWED_URLS=
# Interface
WEBAPP_URL=file:///./webapp/index.html
WINDOW_WIDTH=1024
WINDOW_HEIGHT=768
# Logging
LOG_LEVEL=INFO
ENABLE_LOGGING=true
```
## Testing ## Testing
- Unit tests: `pytest tests/unit/ -v` WebDrop Bridge includes comprehensive test coverage with unit, integration, and end-to-end tests.
- Integration tests: `pytest tests/integration/ -v`
- Coverage: `pytest --cov=src/webdrop_bridge`
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 ## 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 ## Changelog
@ -160,23 +222,52 @@ See [CHANGELOG.md](CHANGELOG.md) for release notes.
## Building Installers ## Building Installers
### Windows MSI ### Windows MSI Installer
```bash ```bash
pip install pyinstaller # Simple build (creates standalone .exe)
python build/scripts/build_windows.py 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 ```bash
pip install pyinstaller # Build DMG (requires macOS)
bash build/scripts/build_macos.sh 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 ## Development Workflow
@ -249,13 +340,35 @@ MIT License - see [LICENSE](LICENSE) file for details
- Inspired by professional desktop integration practices - Inspired by professional desktop integration practices
- Special thanks to the Qt community - 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 ## Roadmap
- [ ] v1.0 - Stable Windows & macOS release - [x] Core drag-drop functionality
- [ ] v1.1 - Advanced filtering and logging UI - [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 - [ ] v1.2 - API for custom handlers
- [ ] v2.0 - Plugin architecture - [ ] v2.0 - Plugin architecture
- [ ] v2.1 - Cloud storage integration (OneDrive, Google Drive)
## Support ## 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)