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
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:
parent
4ab44c83ba
commit
c9704efc8d
1 changed files with 148 additions and 35 deletions
181
README.md
181
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.)
|
||||
|
||||
  
|
||||
  
|
||||
|
||||
## 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
|
||||
# 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)
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue