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.)
![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)