Add desktop GUI and build scripts for DocFinder

[filippostanghellini]

Introduces a native desktop GUI launcher using pywebview, with platform-specific build scripts and GitHub Actions workflow for packaging macOS, Windows, and Linux apps. Updates Makefile, README, and pyproject.toml to support GUI installation and usage. Improves config handling for default database paths and enhances error messaging in the web API.

Description

This PR adds a complete desktop application experience to DocFinder. Users can now download and install DocFinder as a native app on macOS, Windows, and Linux without needing Python installed. The app uses pywebview to wrap the existing FastAPI web interface in a native window.

Type of Change

• 🐛 Bug fix (non-breaking change which fixes an issue)
• ✨ New feature (non-breaking change which adds functionality)
• 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
• 📝 Documentation update
• 🎨 Code style update (formatting, renaming)
• ♻️ Code refactor (no functional changes)
• ⚡ Performance improvement
• ✅ Test update
• 🔧 Configuration change
• 🏗️ Build/CI update

Related Issues

Related to #13

Changes Made

• Add src/docfinder/gui.py - Desktop GUI launcher using pywebview
• Add DocFinder.spec - PyInstaller configuration for bundling
• Add scripts/build-macos.sh - macOS build script (creates .app and .dmg)
• Add scripts/build-windows.ps1 - Windows build script (creates NSIS installer)
• Add scripts/build-linux.sh - Linux build script (creates AppImage)
• Add .github/workflows/build-desktop.yml - CI workflow for multi-platform builds
• Update pyproject.toml - Add [gui] extras and docfinder-gui entry point
• Update Makefile - Add install-gui and build-* targets
• Update README.md - Add desktop installation instructions
• Update config.py - Smart database path resolution for frozen apps
• Update web/app.py - Improved error messages for missing database

Testing

• Existing tests pass locally
• Added new tests for the changes
• Manual testing performed

Manual Testing

• ✅ Built macOS app with make build-macos
• ✅ App launches and displays native window
• ✅ Search functionality works with existing database
• ✅ Indexing functionality works from GUI

Checklist

• My code follows the project's code style (passes ruff check and ruff format)
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published

Screenshots (if applicable)

Desktop app running on macOS with native window wrapper.

Additional Context

The desktop app stores its database in ~/Documents/DocFinder/docfinder.db to ensure data persists across app updates. The app is unsigned, so users need to bypass Gatekeeper (macOS) or SmartScreen (Windows) on first launch - instructions are included in the README.

Deployment Notes

• New GitHub Actions workflow will automatically build installers when a release is created
• Release assets will include: DocFinder-macOS.dmg, DocFinder-Windows-Setup.exe, DocFinder-Linux-x86_64.AppImage
• First release should be tagged as v1.0.0

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

OpenSSF Scorecard

Package	Version	Score	Details
actions/actions/checkout	5.*.*	🟢 6.2	Details Check Score Reason Maintained ⚠️ 1 2 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 1 Code-Review 🟢 10 all changesets reviewed Binary-Artifacts 🟢 10 no binaries found in the repo CII-Best-Practices ⚠️ 0 no effort to earn an OpenSSF best practices badge detected Dangerous-Workflow 🟢 10 no dangerous workflow patterns detected Fuzzing ⚠️ 0 project is not fuzzed License 🟢 10 license file detected Signed-Releases ⚠️ -1 no releases found Packaging ⚠️ -1 packaging workflow not detected Security-Policy 🟢 9 security policy file detected Token-Permissions ⚠️ 0 detected GitHub workflow tokens with excessive permissions Branch-Protection ⚠️ -1 internal error: error during GetBranch(releases/v5): error during branchesHandler.query: internal error: githubv4.Query: Resource not accessible by integration Pinned-Dependencies 🟢 3 dependency not pinned by hash detected -- score normalized to 3 Vulnerabilities 🟢 9 1 existing vulnerabilities detected SAST 🟢 8 SAST tool detected but not run on all commits
actions/actions/download-artifact	4.*.*	🟢 5.5	Details Check Score Reason Packaging ⚠️ -1 packaging workflow not detected Dangerous-Workflow 🟢 10 no dangerous workflow patterns detected Maintained 🟢 9 11 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 9 Code-Review 🟢 10 all changesets reviewed CII-Best-Practices ⚠️ 0 no effort to earn an OpenSSF best practices badge detected License 🟢 10 license file detected Binary-Artifacts 🟢 10 no binaries found in the repo Token-Permissions ⚠️ 0 detected GitHub workflow tokens with excessive permissions Fuzzing ⚠️ 0 project is not fuzzed Signed-Releases ⚠️ -1 no releases found Security-Policy 🟢 9 security policy file detected Pinned-Dependencies ⚠️ 1 dependency not pinned by hash detected -- score normalized to 1 Branch-Protection ⚠️ 0 branch protection not enabled on development/release branches SAST 🟢 9 SAST tool detected but not run on all commits Vulnerabilities ⚠️ 0 11 existing vulnerabilities detected
actions/actions/setup-python	5.*.*	🟢 5.7	Details Check Score Reason Code-Review 🟢 10 all changesets reviewed Maintained 🟢 10 12 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 10 Binary-Artifacts 🟢 10 no binaries found in the repo CII-Best-Practices ⚠️ 0 no effort to earn an OpenSSF best practices badge detected Packaging ⚠️ -1 packaging workflow not detected Dangerous-Workflow 🟢 10 no dangerous workflow patterns detected Token-Permissions ⚠️ 0 detected GitHub workflow tokens with excessive permissions License 🟢 10 license file detected Fuzzing ⚠️ 0 project is not fuzzed Pinned-Dependencies ⚠️ 0 dependency not pinned by hash detected -- score normalized to 0 Signed-Releases ⚠️ -1 no releases found Security-Policy 🟢 9 security policy file detected SAST 🟢 9 SAST tool is not run on all commits -- score normalized to 9 Vulnerabilities ⚠️ 2 8 existing vulnerabilities detected Branch-Protection ⚠️ 0 branch protection not enabled on development/release branches
actions/actions/upload-artifact	4.*.*	🟢 5.6	Details Check Score Reason Code-Review 🟢 10 all changesets reviewed Maintained 🟢 6 8 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 6 Binary-Artifacts 🟢 10 no binaries found in the repo Packaging ⚠️ -1 packaging workflow not detected Dangerous-Workflow 🟢 10 no dangerous workflow patterns detected Token-Permissions ⚠️ 0 detected GitHub workflow tokens with excessive permissions CII-Best-Practices ⚠️ 0 no effort to earn an OpenSSF best practices badge detected Fuzzing ⚠️ 0 project is not fuzzed License 🟢 10 license file detected Pinned-Dependencies ⚠️ 1 dependency not pinned by hash detected -- score normalized to 1 Signed-Releases ⚠️ -1 no releases found Security-Policy 🟢 9 security policy file detected Branch-Protection ⚠️ 0 branch protection not enabled on development/release branches SAST 🟢 9 SAST tool detected but not run on all commits Vulnerabilities 🟢 4 6 existing vulnerabilities detected
actions/softprops/action-gh-release	1.*.*	🟢 5.2	Details Check Score Reason Dangerous-Workflow 🟢 10 no dangerous workflow patterns detected Packaging ⚠️ -1 packaging workflow not detected Maintained 🟢 10 26 commit(s) and 5 issue activity found in the last 90 days -- score normalized to 10 Token-Permissions ⚠️ 0 detected GitHub workflow tokens with excessive permissions Code-Review 🟢 3 Found 3/10 approved changesets -- score normalized to 3 Binary-Artifacts 🟢 10 no binaries found in the repo Pinned-Dependencies 🟢 10 all dependencies are pinned CII-Best-Practices ⚠️ 0 no effort to earn an OpenSSF best practices badge detected Fuzzing ⚠️ 0 project is not fuzzed Security-Policy ⚠️ 0 security policy file not detected License 🟢 10 license file detected Vulnerabilities 🟢 9 1 existing vulnerabilities detected Branch-Protection ⚠️ 0 branch protection not enabled on development/release branches Signed-Releases ⚠️ -1 no releases found SAST ⚠️ 0 SAST tool is not run on all commits -- score normalized to 0

Scanned Files

• .github/workflows/build-desktop.yml

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

❌ Patch coverage is 12.63158% with 83 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/docfinder/gui.py	0.00%	79 Missing ⚠️
src/docfinder/config.py	80.00%	3 Missing ⚠️
src/docfinder/web/app.py	0.00%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!