fix(electron): added macos file associations

2025-08-11 08:30:44 -04:00
parent 6c53e9ca6c
commit d7d7615376
18 changed files with 2497 additions and 43 deletions
--- a/electron/PKG_INSTALLER_GUIDE.md
+++ b/electron/PKG_INSTALLER_GUIDE.md
@@ -0,0 +1,242 @@
+# 4DSTAR Bundle Manager .pkg Installer Guide
+
+## Overview
+
+The 4DSTAR Bundle Manager now includes a professional macOS `.pkg` installer that provides a seamless installation experience with automatic file association setup and dependency guidance.
+
+## What's Included
+
+### 📦 **Professional Installer Package**
+- Native macOS `.pkg` installer format
+- Automatic Launch Services refresh
+- File association setup
+- Custom icon registration
+- Dependency information dialogs
+
+### 🔧 **Automatic Post-Install Setup**
+- Launch Services database refresh
+- File association registration
+- Icon cache clearing
+- Finder restart for immediate functionality
+
+### 📋 **User Guidance**
+- Welcome dialog explaining system requirements
+- Clear distinction between basic and advanced usage
+- Optional dependency installation instructions
+- Conclusion dialog with next steps
+
+## Installation Experience
+
+### 1. **Welcome Screen**
+Users see a comprehensive welcome dialog that explains:
+- **Basic Usage**: No dependencies required for bundle management
+- **Advanced Usage**: Docker and Meson needed for plugin building
+- **System Requirements**: macOS 10.12+ minimum
+- **What's Included**: App, file associations, custom icons
+
+### 2. **Standard macOS Installation**
+- License agreement (if configured)
+- Installation destination (defaults to /Applications)
+- Administrator password prompt
+- Installation progress
+
+### 3. **Automatic Post-Install**
+The installer automatically:
+- Refreshes Launch Services database
+- Registers file associations for .fbundle and .opat files
+- Clears icon caches
+- Restarts Finder
+- Logs all operations to `/tmp/4dstar-postinstall.log`
+
+### 4. **Conclusion Screen**
+Users see a success dialog with:
+- Installation confirmation
+- Getting started instructions
+- Optional dependency installation commands
+- Troubleshooting information
+
+## File Associations
+
+### Supported File Types
+- **`.fbundle`**: 4DSTAR Plugin Bundle Files
+- **`.opat`**: OPAT Data Files
+
+### What Works After Installation
+- ✅ Double-click files to open in 4DSTAR Bundle Manager
+- ✅ Right-click → "Open with 4DSTAR Bundle Manager"
+- ✅ Custom file icons in Finder
+- ✅ Proper file type descriptions
+- ✅ Immediate functionality (no restart required)
+
+## Dependencies
+
+### Required (Always)
+- macOS 10.12 or later
+- No additional dependencies for basic bundle management
+
+### Optional (Advanced Features)
+- **Docker Desktop**: For cross-platform plugin builds
+- **Meson Build System**: For native plugin compilation
+- **Xcode Command Line Tools**: For C++ compilation
+
+### Installation Commands (Optional)
+```bash
+# Install Xcode Command Line Tools
+xcode-select --install
+
+# Install Meson via Homebrew
+brew install meson
+
+# Download Docker Desktop
+# Visit: https://docker.com/products/docker-desktop
+```
+
+## Build Configuration
+
+### Package.json Configuration
+```json
+{
+  "build": {
+    "mac": {
+      "target": [
+        { "target": "dmg", "arch": ["x64", "arm64"] },
+        { "target": "pkg", "arch": ["x64", "arm64"] },
+        { "target": "zip", "arch": ["x64", "arm64"] }
+      ]
+    },
+    "pkg": {
+      "scripts": "installer-scripts",
+      "welcome": "installer-resources/welcome.html",
+      "conclusion": "installer-resources/conclusion.html",
+      "installLocation": "/Applications",
+      "mustClose": ["com.fourdst.bundlemanager"]
+    }
+  }
+}
+```
+
+### File Structure
+```
+electron/
+├── installer-scripts/
+│   └── postinstall              # Post-install script
+├── installer-resources/
+│   ├── welcome.html            # Welcome dialog
+│   └── conclusion.html         # Conclusion dialog
+├── icons/
+│   ├── app-icon.icns          # Main app icon
+│   ├── fbundle-icon.icns      # .fbundle file icon
+│   └── opat-icon.icns         # .opat file icon
+└── package.json               # Build configuration
+```
+
+## Building the Installer
+
+### Generate All Installers
+```bash
+npm run build
+```
+
+### Generate Only .pkg
+```bash
+npx electron-builder --mac pkg
+```
+
+### Output Files
+- `dist/4DSTAR Bundle Manager-1.0.0.pkg` (x64)
+- `dist/4DSTAR Bundle Manager-1.0.0-arm64.pkg` (ARM64)
+- Plus traditional .dmg and .zip files
+
+## Post-Install Script Details
+
+### What It Does
+```bash
+#!/bin/bash
+# Reset Launch Services database
+lsregister -kill -r -domain local -domain system -domain user
+
+# Register the app bundle
+lsregister -f "/Applications/4DSTAR Bundle Manager.app"
+
+# Clear icon caches
+rm -rf ~/Library/Caches/com.apple.iconservices.store
+rm -rf /Library/Caches/com.apple.iconservices.store
+
+# Restart Finder
+killall Finder
+```
+
+### Logging
+All operations are logged to `/tmp/4dstar-postinstall.log` for troubleshooting.
+
+## Troubleshooting
+
+### If File Associations Don't Work
+1. Check post-install log: `cat /tmp/4dstar-postinstall.log`
+2. Manually refresh: `npm run refresh-icons`
+3. Right-click file → Get Info → Change default app
+
+### If Icons Don't Appear
+1. Wait 2-3 minutes for macOS to update
+2. Log out and back in
+3. Restart the Mac
+4. Check icon cache clearing in post-install log
+
+### If Installation Fails
+1. Ensure you have administrator privileges
+2. Close any running instances of the app
+3. Check available disk space (>200MB required)
+4. Try installing from a different location
+
+## Developer Notes
+
+### Testing the Installer
+1. Build the .pkg installer
+2. Test on a clean macOS system or VM
+3. Verify file associations work immediately
+4. Check that icons appear in Finder
+5. Test with both .fbundle and .opat files
+
+### Customizing Dialogs
+- Edit `installer-resources/welcome.html` for welcome content
+- Edit `installer-resources/conclusion.html` for conclusion content
+- HTML/CSS styling is supported
+- Keep content concise and user-friendly
+
+### Modifying Post-Install Script
+- Edit `installer-scripts/postinstall`
+- Ensure script remains executable: `chmod +x postinstall`
+- Test thoroughly on different macOS versions
+- Add logging for all operations
+
+## Distribution
+
+### Recommended Distribution Method
+1. **Primary**: `.pkg` installer for best user experience
+2. **Alternative**: `.dmg` for users who prefer disk images
+3. **Developer**: `.zip` for automated deployment
+
+### Code Signing (Production)
+For production distribution:
+1. Obtain Apple Developer ID certificate
+2. Configure code signing in package.json
+3. Notarize the installer with Apple
+4. Test on systems with Gatekeeper enabled
+
+## User Support
+
+### Common User Questions
+
+**Q: Do I need Docker to use the app?**
+A: No, Docker is only needed for building plugins. Basic bundle management works without any additional software.
+
+**Q: Why do I need administrator privileges?**
+A: The installer needs to install the app to /Applications and register file associations system-wide.
+
+**Q: Can I install to a different location?**
+A: The .pkg installer installs to /Applications by default. Use the .dmg version for custom locations.
+
+**Q: Will this work on older Macs?**
+A: Yes, the app supports macOS 10.12 and later on both Intel and Apple Silicon Macs.
+
+This comprehensive installer solution provides a professional, user-friendly installation experience that handles all technical setup automatically while clearly communicating optional dependencies to users.