v2.2.1: Add Homebrew support and macOS Gatekeeper fix script

Author: ashesbloom

.github/workflows/release.yml

@@ -129,6 +129,59 @@ jobs:
             echo "No DMG found for checksums"
           fi
 
+      - name: Create macOS Gatekeeper fix script
+        run: |
+          cat > "Fix_Local_Lens.command" << 'SCRIPT'
+          #!/bin/bash
+          # Local Lens - macOS Gatekeeper Fix
+          # Double-click this file after copying Local Lens to Applications
+          
+          echo ""
+          echo "🔧 Local Lens - Fixing macOS Security Block"
+          echo "============================================"
+          echo ""
+          
+          APP_PATH="/Applications/Local Lens.app"
+          USER_APP_PATH="$HOME/Applications/Local Lens.app"
+          
+          if [ -d "$APP_PATH" ]; then
+              TARGET="$APP_PATH"
+              echo "Found app in /Applications"
+          elif [ -d "$USER_APP_PATH" ]; then
+              TARGET="$USER_APP_PATH"
+              echo "Found app in ~/Applications"
+          else
+              echo "❌ Local Lens not found in Applications!"
+              echo ""
+              echo "Please:"
+              echo "1. Drag 'Local Lens.app' to your Applications folder first"
+              echo "2. Then run this script again"
+              echo ""
+              read -p "Press Enter to close..."
+              exit 1
+          fi
+          
+          echo "Fixing: $TARGET"
+          echo ""
+          
+          echo "Step 1/3: Removing quarantine flag..."
+          xattr -cr "$TARGET"
+          
+          echo "Step 2/3: Applying ad-hoc signature..."
+          codesign --force --deep --sign - "$TARGET" 2>/dev/null || echo "  (signature step skipped)"
+          
+          echo "Step 3/3: Setting executable permissions..."
+          chmod -R +x "$TARGET/Contents/MacOS/"
+          chmod -R +x "$TARGET/Contents/Resources/backend_server_bundle/" 2>/dev/null || true
+          
+          echo ""
+          echo "✅ Done! You can now open Local Lens normally."
+          echo ""
+          read -p "Press Enter to close..."
+          SCRIPT
+          chmod +x "Fix_Local_Lens.command"
+          echo "Created Fix_Local_Lens.command"
+
       - name: Upload macOS artifacts
         uses: actions/upload-artifact@v4
         with:
@@ -138,6 +191,7 @@ jobs:
             frontend/src-tauri/target/release/bundle/dmg/checksums-macos.txt
             frontend/src-tauri/target/release/bundle/macos/*.app.tar.gz
             frontend/src-tauri/target/release/bundle/macos/*.app.tar.gz.sig
+            Fix_Local_Lens.command
           retention-days: 5
 
   # ============================================================================
@@ -323,6 +377,7 @@ jobs:
           TARBALL=$(find artifacts/macos -name "*.app.tar.gz" 2>/dev/null | head -1)
           TARBALL_SIG=$(find artifacts/macos -name "*.app.tar.gz.sig" 2>/dev/null | head -1)
           CHECKSUMS_MAC=$(find artifacts/macos -name "checksums-macos.txt" 2>/dev/null | head -1)
+          FIX_SCRIPT=$(find artifacts/macos -name "Fix_Local_Lens.command" 2>/dev/null | head -1)
           
           echo "msi_path=$MSI_FILE" >> $GITHUB_OUTPUT
           echo "msi_sig_path=$MSI_SIG" >> $GITHUB_OUTPUT
@@ -332,6 +387,14 @@ jobs:
           echo "tarball_path=$TARBALL" >> $GITHUB_OUTPUT
           echo "tarball_sig_path=$TARBALL_SIG" >> $GITHUB_OUTPUT
           echo "checksums_mac_path=$CHECKSUMS_MAC" >> $GITHUB_OUTPUT
+          echo "fix_script_path=$FIX_SCRIPT" >> $GITHUB_OUTPUT
+          
+          # Get DMG SHA256 for Homebrew cask
+          if [ -n "$DMG_FILE" ] && [ -f "$DMG_FILE" ]; then
+            DMG_SHA256=$(shasum -a 256 "$DMG_FILE" | awk '{print $1}')
+            echo "dmg_sha256=$DMG_SHA256" >> $GITHUB_OUTPUT
+            echo "DMG SHA256: $DMG_SHA256"
+          fi
           
           # Read signatures for latest.json
           if [ -n "$MSI_SIG" ] && [ -f "$MSI_SIG" ]; then
@@ -353,13 +416,83 @@ jobs:
           win_sig="${{ steps.find_files.outputs.win_signature }}"
           mac_sig="${{ steps.find_files.outputs.mac_signature }}"
           
-          # Generate latest.json using printf to avoid heredoc YAML issues
-          printf '{\n  "version": "%s",\n  "notes": "See release notes on GitHub",\n  "pub_date": "%s",\n  "platforms": {\n    "windows-x86_64": {\n      "signature": "%s",\n      "url": "https://github.com/%s/releases/download/%s/Local_Lens_%s_x64_en-US.msi"\n    },\n    "darwin-aarch64": {\n      "signature": "%s",\n      "url": "https://github.com/%s/releases/download/%s/Local_Lens.app.tar.gz"\n    }\n  }\n}\n' \
-            "$version" "$pub_date" "$win_sig" "$repo" "$tag" "$tag" "$mac_sig" "$repo" "$tag" > latest.json
+          # Get release notes
+          notes="${{ steps.release_notes.outputs.notes }}"
+          
+          # Use jq to generate valid JSON with proper escaping
+          jq -n \
+            --arg version "$version" \
+            --arg notes "$notes" \
+            --arg pub_date "$pub_date" \
+            --arg win_sig "$win_sig" \
+            --arg win_url "https://github.com/$repo/releases/download/$tag/Local_Lens_${tag}_x64_en-US.msi" \
+            --arg mac_sig "$mac_sig" \
+            --arg mac_url "https://github.com/$repo/releases/download/$tag/Local_Lens.app.tar.gz" \
+            '{
+              version: $version,
+              notes: $notes,
+              pub_date: $pub_date,
+              platforms: {
+                "windows-x86_64": {
+                  signature: $win_sig,
+                  url: $win_url
+                },
+                "darwin-aarch64": {
+                  signature: $mac_sig,
+                  url: $mac_url
+                }
+              }
+            }' > latest.json
           
           echo "Generated latest.json:"
           cat latest.json
 
+      - name: Generate Homebrew Cask formula
+        run: |
+          version="${{ steps.get_version.outputs.version }}"
+          sha256="${{ steps.find_files.outputs.dmg_sha256 }}"
+          
+          cat > local-lens.rb << EOF
+          cask "local-lens" do
+            version "$version"
+            sha256 "$sha256"
+
+            url "https://github.com/${{ github.repository }}/releases/download/v#{version}/Local_Lens_v#{version}_aarch64.dmg",
+                verified: "github.com/${{ github.repository }}/"
+            name "Local Lens"
+            desc "AI-powered offline photo organizer with face recognition"
+            homepage "https://github.com/${{ github.repository }}"
+
+            livecheck do
+              url :url
+              strategy :github_latest
+            end
+
+            auto_updates true
+            depends_on arch: :arm64
+
+            app "Local Lens.app"
+
+            postflight do
+              system_command "/usr/bin/xattr",
+                             args: ["-cr", "#{appdir}/Local Lens.app"],
+                             sudo: false
+            end
+
+            zap trash: [
+              "~/.config/LocalLens",
+            ]
+
+            caveats <<~EOS
+              Local Lens is not notarized by Apple.
+              If you see a security warning, right-click the app → Open → Click "Open"
+            EOS
+          end
+          EOF
+          
+          echo "Generated Homebrew Cask formula:"
+          cat local-lens.rb
+
       - name: Create Release
         id: create_release
         uses: actions/create-release@v1
@@ -377,46 +510,58 @@ jobs:
             
             ---
             
-            ### 🔒 Security & Verification
+            ### � Installation
             
-            This release was built automatically using GitHub Actions for Windows and macOS:
+            #### 🍺 macOS via Homebrew (Recommended)
+            ```bash
+            brew install ashesbloom/locallens/local-lens
+            ```
+            > Homebrew automatically handles Gatekeeper - no extra steps needed!
             
-            - **Source Code**: Available in this repository at tag `${{ github.ref_name }}`
-            - **Build Process**: View the complete build log in the [Actions tab](https://github.com/${{ github.repository }}/actions)
-            - **Checksums**: SHA256 checksums provided for file verification
+            #### 🪟 Windows
+            1. Download the `.msi` (enterprise) or `.exe` (individual) installer
+            2. Run the installer
+            3. Launch Local Lens from the Start Menu
             
-            ### 📥 Downloads
+            #### 🍎 macOS Manual Install (DMG)
+            1. Download `Local_Lens_${{ github.ref_name }}_aarch64.dmg`
+            2. Open the DMG and drag **Local Lens** to Applications
+            3. **Fix Gatekeeper block** (choose one):
+               - **Easy:** Download and double-click `Fix_Local_Lens.command`
+               - **Manual:** Right-click the app → Open → Click "Open" in the dialog
+               - **Terminal:**
+                 ```bash
+                 xattr -cr "/Applications/Local Lens.app" && codesign --force --deep --sign - "/Applications/Local Lens.app"
+                 ```
             
-            **Windows:**
-            - **MSI Installer**: Recommended for enterprise/managed environments
-            - **EXE Installer**: Recommended for individual users
+            ---
             
-            **macOS (Apple Silicon):**
-            - **DMG**: Drag and drop to Applications folder
+            ### ⚠️ macOS Security Note
             
-            ### ✅ File Verification
+            Local Lens is **not notarized** with Apple (requires $99/year developer fee).
+            macOS may show a "damaged" or "unidentified developer" warning - this is normal for open-source apps.
             
-            **Windows:**
-            ```cmd
-            certutil -hashfile "installer_name" SHA256
-            ```
+            The `Fix_Local_Lens.command` script automatically:
+            - Removes the quarantine flag
+            - Applies an ad-hoc code signature
+            - Sets correct executable permissions
             
-            **macOS:**
-            ```bash
-            shasum -a 256 "Local Lens.dmg"
-            ```
+            ---
+            
+            ### 🔒 Security & Verification
             
-            ### 🚀 Installation
+            - **Source Code**: Available at tag `${{ github.ref_name }}`
+            - **Build Process**: [View build logs](https://github.com/${{ github.repository }}/actions)
+            - **Checksums**: SHA256 checksums provided for verification
             
-            **Windows:**
-            1. Download your preferred installer format
-            2. Run the installer (Admin recommended for MSI)
-            3. Launch Local Lens from Start Menu
+            **Verify downloads:**
+            ```bash
+            # macOS
+            shasum -a 256 "Local_Lens_${{ github.ref_name }}_aarch64.dmg"
             
-            **macOS:**
-            1. Download the DMG file
-            2. Open the DMG and drag Local Lens to Applications
-            3. First launch: Right-click → Open (to bypass Gatekeeper)
+            # Windows
+            certutil -hashfile "Local_Lens_${{ github.ref_name }}_x64-setup.exe" SHA256
+            ```
 
       # Upload Windows artifacts
       - name: Upload MSI installer
@@ -486,6 +631,27 @@ jobs:
           asset_name: checksums-macos.txt
           asset_content_type: text/plain
 
+      - name: Upload macOS fix script
+        if: steps.find_files.outputs.fix_script_path
+        uses: actions/upload-release-asset@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          upload_url: ${{ steps.create_release.outputs.upload_url }}
+          asset_path: ${{ steps.find_files.outputs.fix_script_path }}
+          asset_name: Fix_Local_Lens.command
+          asset_content_type: application/x-sh
+
+      - name: Upload Homebrew Cask formula
+        uses: actions/upload-release-asset@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          upload_url: ${{ steps.create_release.outputs.upload_url }}
+          asset_path: local-lens.rb
+          asset_name: local-lens.rb
+          asset_content_type: text/x-ruby
+
       # Upload latest.json for Tauri auto-updater
       - name: Upload latest.json
         uses: actions/upload-release-asset@v1
@@ -502,6 +668,7 @@ jobs:
           echo "✅ Release created successfully!"
           echo "📦 Uploaded artifacts:"
           echo "   Windows: MSI, EXE, checksums"
-          echo "   macOS: DMG, app tarball, checksums"
+          echo "   macOS: DMG, app tarball, checksums, Fix_Local_Lens.command"
           echo "📋 latest.json generated for auto-updater (Windows + macOS)"
+          echo "🍺 local-lens.rb generated for Homebrew tap"
           echo "🔒 Release created as draft - review and publish manually"

CHANGELOG.md

@@ -5,6 +5,29 @@ All notable changes to Local Lens will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.2.1] - 2025-12-31
+
+### Added
+
+- **Homebrew Cask Support**: macOS users can now install via `brew install ashesbloom/locallens/local-lens`
+  - Homebrew automatically handles Gatekeeper - no manual steps needed
+  - Auto-generated cask formula included in each release
+- **macOS Gatekeeper Fix Script**: `Fix_Local_Lens.command` included in releases
+  - Double-click to automatically remove quarantine, apply ad-hoc signature, and set permissions
+  - Supports both `/Applications` and `~/Applications` install locations
+- Improved release notes with clear macOS installation instructions
+
+### Changed
+
+- Updated README with Quick Install section for all platforms
+- Release workflow now generates Homebrew cask formula automatically
+- Enhanced macOS installation documentation with multiple fix options
+
+### Fixed
+
+- Fixed macOS "App is damaged" error by providing proper workarounds
+- Fixed path escaping issues in terminal commands (use quotes instead of backslashes)
+
 ## [2.2.0] - 2025-12-24
 
 ### Added

README.md

@@ -29,6 +29,30 @@
 </div>
 <br />
 
+## � Quick Install
+
+### macOS (Homebrew) — Recommended
+```bash
+brew install ashesbloom/locallens/local-lens
+```
+> Homebrew handles Gatekeeper automatically — no extra steps needed!
+
+### macOS (Manual DMG)
+1. Download the `.dmg` from [Releases](https://github.com/ashesbloom/LocalLens/releases/latest)
+2. Drag **Local Lens** to Applications
+3. **Fix Gatekeeper** (required for unsigned apps):
+   - Download and double-click `Fix_Local_Lens.command` from the release
+   - Or: Right-click the app → Open → Click "Open"
+   - Or run in Terminal:
+     ```bash
+     xattr -cr "/Applications/Local Lens.app" && codesign --force --deep --sign - "/Applications/Local Lens.app"
+     ```
+
+### Windows
+Download and run the `.msi` or `.exe` installer from [Releases](https://github.com/ashesbloom/LocalLens/releases/latest).
+
+<br />
+
 ## 🖥️ Software Preview
 
 See how Local Lens organizes thousands of photos in seconds: