fourdst/electron/PKG_INSTALLER_GUIDE.md

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)

# 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

{
  "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

npm run build

Generate Only .pkg

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

#!/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.