[BUG] macOS setup friction + stale runtime_deps_check code in main.py prevents clean launch

[edwardexe]

Hi @sgeraldes,

Thanks for creating HiDock Next — it's a fantastic open-source tool!
I finally got the desktop app running on macOS, but the initial setup was quite painful and required several workarounds. Here's a summary of what I encountered so other macOS users (and future contributors) can have a smoother experience.

Issues found:

run-desktop.sh and setup-unix.sh fail on macOS
→ Error: Failed to resolve/ensure virtual environment. Run: python scripts/env/select_venv.py --ensure --print
(The select_venv.py helper seems missing or incompatible with current structure.)
Stale code in apps/desktop/main.py (this was the blocker)
Line 39: from scripts.runtime_deps_check import check_and_handle_runtime_deps
The file scripts/runtime_deps_check.py no longer exists in the repo.
This causes a ModuleNotFoundError, and after commenting the import, a NameError on the function call.
I had to manually comment out both the import and the call in def main() to get the GUI to start.

PYTHONPATH / editable install problems
Root-level scripts/ folder is not automatically importable after pip install -e ".[dev]".
Other minor macOS notes
Must use Python 3.12 (3.13 breaks Tkinter with toast notifications).
brew install libusb + Privacy & Security permission prompt required.

What ultimately worked:

Manual creation of apps/desktop/.venv.mac with Python 3.12
pip install -e ".[dev]" --no-deps
Adding repo root to PYTHONPATH
Commenting out the broken runtime check
Simple alias + launcher script for easy future starts

Once past setup, the app launches cleanly and detects the HiDock device after granting USB permissions.
Suggested fixes:

Clean up / remove the obsolete runtime_deps_check references in main.py
Make ./run-desktop.sh more robust with better fallback for existing venvs
Clearly document Python 3.12 requirement + macOS setup steps
(Optional) Add a simple launch-macos.sh for users who prefer manual control

I'm happy to provide the exact diffs I used, test any PRs, or help further.

-dave

GitHub: @edwardexe

[edwardexe]

Hi @sgeraldes,
Here's a clean patch that fixes the main blocker we hit (ModuleNotFoundError / NameError from the stale runtime_deps_check code).
Patch for apps/desktop/main.py

diff --git a/apps/desktop/main.py b/apps/desktop/main.py
--- a/apps/desktop/main.py
+++ b/apps/desktop/main.py
@@ -36,11 +36,10 @@ import traceback

 # Runtime dependency checker (file was removed during refactoring)
-# from scripts.runtime_deps_check import check_and_handle_runtime_deps
+pass  # Runtime dependency check removed (scripts/runtime_deps_check.py no longer exists)

 def main() -> None:
     """Initializes and runs the HiDock Tool application."""
-    # Check runtime dependencies before starting the GUI
-    print("HiDock Desktop - Checking runtime dependencies...")
-    if not check_and_handle_runtime_deps():
-        print("Runtime dependencies check failed or was cancelled.")
-        sys.exit(1)
+    # Runtime dependency checker was removed during refactoring.
+    # Skipping it to allow clean launch on macOS and other platforms.
+    print("HiDock Desktop - Starting...")

     # Set appearance and theme early
     ctk.set_appearance_mode("System")

After applying this patch, the app launches cleanly with ./run-desktop.sh or manually.

[edwardexe]

@sgeraldes Here's a practical improvement for run-desktop.sh that adds a robust fallback for macOS (and other systems where select_venv.py is missing or fails).
This way, users who already have a working .venv.mac (like I created manually) can launch the app immediately without errors.

diff --git a/run-desktop.sh b/run-desktop.sh
index abc1234..def5678 100755
--- a/run-desktop.sh
+++ b/run-desktop.sh
@@ -1,10 +1,28 @@
 #!/bin/bash
 echo "Starting HiDock Desktop Application..."
 
+# Robust macOS fallback - use existing venv if select_venv.py fails
+if [ -d "apps/desktop/.venv.mac" ] && [ -f "apps/desktop/.venv.mac/bin/activate" ]; then
+    echo "Found existing macOS virtual environment. Activating..."
+    source apps/desktop/.venv.mac/bin/activate
+    
+    # Ensure root is in PYTHONPATH so scripts/ and other modules are importable
+    export PYTHONPATH="$(pwd):$PYTHONPATH"
+    
+    # Optional: silence common macOS Tkinter deprecation warnings
+    export TK_SILENCE_DEPRECATION=1
+    
+    echo "Launching HiDock Desktop..."
+    python -m apps.desktop.main
+    exit 0
+fi
+
 # Original logic
 echo "Resolving virtual environment (creating if needed)..."
 python scripts/env/select_venv.py --ensure --print
 
 if [ $? -ne 0 ]; then
     echo "Error: Failed to resolve/ensure virtual environment."
     echo "Run: python scripts/env/select_venv.py --ensure --print"
     read -p "Press Enter to continue..."
     exit 1
 fi

How it helps:

If .venv.mac already exists → it uses it immediately (fast and reliable).
Falls back to the original select_venv.py logic if the venv is missing.
Automatically sets PYTHONPATH so the stale import issues are less likely to bite users.
Adds the TK_SILENCE_DEPRECATION=1 flag that many macOS users need.

This small change would make ./run-desktop.sh work out-of-the-box for most macOS users who follow the manual Python 3.12 + brew install libusb steps.