feat: add native wrappers and cross-platform packaging support [WIP]

[dcoffin88]

Summary

This PR adds MailFlow native app support for Electron desktop and Android via Capacitor, while keeping the existing source changes as minimal as possible.

It introduces the packages and build foundation needed for Windows, macOS, Linux .deb/.rpm, and Android releases, including native notifications, unread badges, quick actions, update flows, platform bridges, app icons, and automatic release versioning.

This work addresses my question in Issue #77.

• Android signing is configured through CI secrets; signing keys are not committed.
• Snap/AppImage support was but intentionally left out at this time.
• I am happy for this branch to be squash-merged due to the large number of incremental packaging/debug commits.

Changes

• Electron native wrapper integration
• Capacitor Android wrapper integration
• Platform bridge architecture between frontend and native runtimes
• Preload/native bridge communication layers
• Platform detection and native runtime handling
• Branded host-unavailable fallback page
• Addressed unsupported tray behaviour on Linux/macOS
• Fixed Electron bridge initialization and update install edge cases

Android Support

• Full Android Capacitor project structure
• Android build automation scripts
• Android artifact collection workflows
• Android app resources and icons
• Android splash screens and launcher assets
• Android release packaging support
• Android build/signing/artifact collection scripts

Electron/Desktop Support

• Electron wrapper functionality
• Native notification forwarding
• Notification bridge between frontend and Electron
• Native quick actions support
• Unread badge synchronization
• Startup update checks
• Silent update flows
• Linux badge API support
• Addressed Electron runtime stability

Linux Packaging & Distribution

• .deb package support
• .rpm package support
• Linux metadata generation
• Linux update flow handling
• Shell-driven Linux updater support
• Package naming normalization
• Linux package compliance metadata
• Libunity dependency support for .rpm unread counter badges

Release & Build Pipeline

• GitHub Actions publishing workflow
• GitHub release-based versioning
• Automated app version synchronization
• Release number integration into application builds
• Automated repackaging and release workflows triggered when new GitHub releases are created
• Addressed CI/CD packaging consistency across targets

Branding & Packaging Improvements

• Replaced default Capacitor icons and splash assets
• Added Electron application icons
• Updated application identifiers to production domain values
• Added homepage/email metadata for package compliance
• Addressed package naming conventions

Runtime & UX Improvements

• Addressed update install flows
• Addressed notification toast handling
• Addressed unread overlay persistence
• Removed unsupported system tray behaviour on Linux/macOS
• Addressed Linux updater edge cases
• Addressed RPM packaging/update behaviour
• Addressed Electron native bridge initialization timing

Dependency & Security Updates

• Addressed package dependencies
• Addressed CVE-2020-27348
• Platform-specific runtime dependencies
• Addressed native package compatibility

Testing

Apps can be tested before merge by using my build branch.

Testing app builds are available from my dev branch of MailFlow:

https://github.com/dcoffin88/mailflow/releases/latest

For full app integration testing, the native apps should also be tested paired with the build branch Docker builds:

ghcr.io/dcoffin88/mailflow-frontend:${MAILFLOW_VERSION:-latest}
ghcr.io/dcoffin88/mailflow-backend:${MAILFLOW_VERSION:-latest}

Tested thoroughly on:

• Windows x64
• macOS Intel x64
• Ubuntu x64
• Fedora x64
• Android

Validation included:

• Fresh installs
• Upgrade/update scenarios
• Native notification flows
• Notification quick actions
• Electron bridge communication
• Android build generation
• Linux package installation
• .deb and .rpm updater flows
• Android build generation
• GitHub release publishing
• Cross-platform packaging verification
• Host unavailable fallback handling
• Badge/unread count synchronization

Notes

This PR is large due to the interconnected nature of these wrappers and cross-platform runtime integration. The changes were grouped together to allow full validation across all supported desktop and mobile targets.

Screenshots

---

Contributor License Agreement

By submitting this pull request I confirm that:

• I have read and agree to the Contributor License Agreement.
• My contribution is my own original work (or I have identified any
  third-party material and confirmed it is compatible with the CLA).
• I have the right to submit this contribution under the terms of the CLA.

[maathimself]

Hey, the overall architecture is solid and the optional chaining throughout means web/PWA users are unaffected. A few things to address before this can be merged:

Bugs:

1. actionLabel/onAction vs onUndo — ElectronNotificationBridge creates a notification with actionLabel: 'Install' and onAction, but the toast component renders action buttons using the onUndo field name. Please verify the Install button actually appears, otherwise the update notification will be persistent but have no way to trigger the install.

2. Inconsistent badge API paths — MailApp.jsx calls window.mailflowNative?.setUnreadCount?.(total) at the top level, but the Capacitor bridge wires up window.mailflowNative.badges.setUnreadCount. One of these will silently do nothing. Please align them.

Code issues:

3. installCapacitorNativeBridge() at component top level — This runs on every render of ElectronNotificationBridge. Move it inside a useEffect(() => { installCapacitorNativeBridge(); }, []).

4. <ElectronNotificationBridge /> rendered unconditionally — This mounts for all users including the plain web app. Consider gating it: {(window.mailflowNative || isElectron) && <ElectronNotificationBridge />} or similar, so non-native users don't pay the cost.

Dependency concern:

5. @capacitor/core in the main bundle — This gets bundled for all users (web, PWA, Electron), not just Android. Consider a dynamic import() inside capacitorNativeBridge.js that only loads Capacitor when actually on a native platform, keeping it out of the main web bundle.

Also happy to squash-merge as you suggested once the above is addressed — the 90-commit history isn't something we need to carry. Let me know