Fix the macOS quarantine hang, and say how to run an unsigned app

Downloading the zip stamps com.apple.quarantine on the bundle and on every one
of the ~450 files inside it. Approving the app in System Settings clears only
the outer one, so dyld stalls checking each nested library: the app bounces in
the Dock and never opens a window, with the main thread parked in _dyld_start
before Python starts. Right-click -> Open does not help, and it looks for all
the world like a crash.

macOS builds now ship a folder containing the app, a double-clickable
Sortero-first-run.command that clears the flag from the whole bundle and
launches it, and a READ ME FIRST explaining why. Verified against a freshly
quarantined copy: 911 flagged files to 0, signature still valid, and the app
reaches its run loop instead of hanging in the loader.

Release notes and the README now lead with this rather than the useless
right-click advice, and cover the Windows SmartScreen and Linux Tk cases too.
Notarisation is the only real fix and needs a paid Apple Developer account.

Also drops PyInstaller's redundant onedir output from the macOS zip. --windowed
emits both dist/Sortero and dist/Sortero.app; the .app is self-contained, so
shipping both put the whole program in twice and took the download from 13 MB
to 27 MB.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: sparkly-quasar

.github/workflows/release.yml

@@ -60,7 +60,7 @@ jobs:
       - name: Verify macOS binary is universal
         if: runner.os == 'macOS'
         run: |
-          BIN=build/dist/Sortero.app/Contents/MacOS/Sortero
+          BIN=build/dist/Sortero/Sortero.app/Contents/MacOS/Sortero
           lipo -archs "$BIN"
           lipo -archs "$BIN" | grep -q x86_64 && lipo -archs "$BIN" | grep -q arm64 \
             || { echo "not universal"; exit 1; }
@@ -85,3 +85,27 @@ jobs:
           name: Sortero ${{ github.event.inputs.tag || github.ref_name }}
           generate_release_notes: true
           files: artifacts/**/*.zip
+          body: |
+            ## Installing
+
+            **macOS** — the app is signed ad-hoc, not notarised (notarising needs a
+            paid Apple Developer account). macOS therefore quarantines every file
+            inside the bundle on download. Approving the app in System Settings only
+            clears the outer one, so it will **bounce in the Dock and never open a
+            window** until the flag is cleared from the whole bundle.
+
+            Unzip, then either double-click `Sortero-first-run.command` (included), or
+            run once:
+
+            ```
+            xattr -dr com.apple.quarantine /Applications/Sortero.app
+            ```
+
+            Then open it normally. Only needed once per download.
+
+            **Windows** — unzip and run `Sortero.exe`. SmartScreen may warn about an
+            unknown publisher; choose More info → Run anyway.
+
+            **Linux** — unzip and run `./Sortero`. Needs Tk (`apt install python3-tk`).
+
+            ---

README.md

@@ -2,9 +2,9 @@
 
 [![License: GPL v3+](https://img.shields.io/badge/License-GPLv3+-blue.svg)](LICENSE)
 
-A macOS app for getting a DJ collection under control: one canonical copy of
-every track, playlists that preserve your curation, clean tags, and an intake
-lane for new music.
+A cross-platform desktop app for getting a DJ collection under control: one
+canonical copy of every track, playlists that preserve your curation, clean
+tags, and an intake lane for new music. Runs on macOS, Windows and Linux.
 
 ![tabs: Overview, Organise, Tags, Duplicates, Import, History](build/icon_1024.png)
 
@@ -122,8 +122,27 @@ from the [Releases page](../../releases):
 | Windows | `Sortero-windows-x86_64.zip` |
 | Linux | `Sortero-linux-x86_64.zip` |
 
-macOS builds are ad-hoc signed, not notarised, so the first launch needs
-right-click → Open.
+### macOS: clear the quarantine flag first
+
+Builds are signed ad-hoc, not notarised — notarising requires a paid Apple
+Developer account. macOS stamps a quarantine flag on the app **and on every one
+of the ~450 files inside it** when you download the zip. Approving the app in
+System Settings only clears the outer bundle, so the dynamic loader stalls on
+the nested libraries: **the app bounces in the Dock and no window ever appears.**
+Right-click → Open does not fix this.
+
+Unzip, then either double-click the included `Sortero-first-run.command`, or run:
+
+```bash
+xattr -dr com.apple.quarantine /Applications/Sortero.app
+```
+
+Then open Sortero normally. Only needed once per download. If Sortero is in
+`/Applications`, macOS may ask permission before another program can modify apps
+there — approve it, or run the app from `~/Downloads` instead.
+
+**Windows** — SmartScreen may warn about an unknown publisher; More info → Run anyway.
+**Linux** — needs Tk (`apt install python3-tk`).
 
 ### Building from source
 

build/Sortero-first-run.command

@@ -0,0 +1,49 @@
+#!/bin/bash
+# Sortero — macOS first run
+#
+# Sortero is signed ad-hoc rather than notarised (that needs a paid Apple
+# Developer account). When macOS downloads the zip it stamps a "quarantine"
+# flag on the app AND on every one of the ~450 files inside it. Approving the
+# app in System Settings only clears the flag on the outer bundle, so the
+# loader stalls checking each nested library — the app bounces in the Dock and
+# no window ever appears.
+#
+# This script clears that flag from the whole bundle and launches the app.
+# It changes nothing else, and does not need your password.
+
+set -u
+DIR="$(cd "$(dirname "$0")" && pwd)"
+
+for CANDIDATE in "$DIR/Sortero.app" "/Applications/Sortero.app" "$HOME/Applications/Sortero.app"; do
+    if [ -d "$CANDIDATE" ]; then
+        APP="$CANDIDATE"
+        break
+    fi
+done
+
+if [ -z "${APP:-}" ]; then
+    echo "Couldn't find Sortero.app next to this script or in /Applications."
+    echo "Move this script beside Sortero.app and run it again."
+    read -r -p "Press return to close."
+    exit 1
+fi
+
+echo "Clearing the quarantine flag on:"
+echo "  $APP"
+echo
+
+if xattr -dr com.apple.quarantine "$APP" 2>/dev/null; then
+    echo "Done."
+else
+    echo "Couldn't clear it automatically."
+    echo
+    echo "If Sortero is in /Applications, macOS asks permission before another"
+    echo "program may modify apps there. Either approve the prompt and run this"
+    echo "again, or run the app from your Downloads folder instead."
+    read -r -p "Press return to close."
+    exit 1
+fi
+
+echo "Launching Sortero…"
+open "$APP"
+sleep 1

build/build_app.py

@@ -95,10 +95,46 @@ def main():
         else:
             arch = "-".join(arches) or "unknown"
         zip_path = os.path.join(DIST, f"Sortero-macOS-{arch}.zip")
+
+        # Ship the first-run helper beside the app. Downloading the zip stamps
+        # com.apple.quarantine on every file inside the bundle, and approving
+        # the app in System Settings only clears the outer one - the loader
+        # then stalls on the nested libraries and no window appears.
+        helper_src = os.path.join(BUILD, "Sortero-first-run.command")
+        payload = os.path.join(DIST, "Sortero")
+        # --windowed also leaves a onedir build at dist/Sortero. The .app is
+        # self-contained, so that folder is dead weight - drop it before reusing
+        # the name for the zip payload, or it ships twice.
+        if os.path.isdir(payload):
+            shutil.rmtree(payload)
+        os.makedirs(payload)
+        shutil.move(app, os.path.join(payload, "Sortero.app"))
+        if os.path.exists(helper_src):
+            helper_dst = os.path.join(payload, "Sortero-first-run.command")
+            shutil.copy2(helper_src, helper_dst)
+            os.chmod(helper_dst, 0o755)
+        readme = os.path.join(payload, "READ ME FIRST.txt")
+        with open(readme, "w") as fh:
+            fh.write(
+                "Sortero for macOS\n"
+                "=================\n\n"
+                "Sortero is signed ad-hoc, not notarised, so macOS quarantines every\n"
+                "file inside the app when you download it. Approving the app in System\n"
+                "Settings only clears the outer bundle, and the app will bounce in the\n"
+                "Dock without ever opening a window.\n\n"
+                "To fix that, once:\n\n"
+                "  1. Drag Sortero.app wherever you want it (Applications is fine).\n"
+                "  2. Double-click 'Sortero-first-run.command'.\n\n"
+                "Or run this in Terminal:\n\n"
+                "  xattr -dr com.apple.quarantine /Applications/Sortero.app\n\n"
+                "After that, open Sortero normally. You only need to do this once per\n"
+                "download.\n")
+
         print("==> zipping (ditto preserves the bundle)")
         subprocess.run(["ditto", "-c", "-k", "--sequesterRsrc", "--keepParent",
-                        app, zip_path], check=True)
-        print(f"\nbuilt {app}\nzip:  {zip_path}  ({os.path.getsize(zip_path)/1e6:.1f} MB)")
+                        payload, zip_path], check=True)
+        print(f"\nbuilt {payload}/Sortero.app\nzip:  {zip_path}  "
+              f"({os.path.getsize(zip_path)/1e6:.1f} MB)")
     else:
         target = os.path.join(DIST, "Sortero")
         plat = "windows" if IS_WIN else "linux"

sortero/version.py

@@ -1 +1 @@
-__version__ = "0.3.0"
+__version__ = "0.3.1"