From 09ae5ee3eb89261743117f833d65f9439c61aea5 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Tue, 3 Feb 2026 14:46:04 +0800
Subject: [PATCH 01/17] chore(deps): bump actions/cache from 5.0.2 to 5.0.3
 (#405)

Bumps [actions/cache](https://github.com/actions/cache) from 5.0.2 to 5.0.3.
- [Release notes](https://github.com/actions/cache/releases)
- [Changelog](https://github.com/actions/cache/blob/main/RELEASES.md)
- [Commits](https://github.com/actions/cache/compare/8b402f58fbc84540c8b491a91e594a4576fec3d7...cdf6c1fa76f9f475f3d7449005a359c84ca0f306)

---
updated-dependencies:
- dependency-name: actions/cache
  dependency-version: 5.0.3
  dependency-type: direct:production
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 .github/workflows/check.yml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/check.yml b/.github/workflows/check.yml
index 716382a..0ddaeeb 100644
--- a/.github/workflows/check.yml
+++ b/.github/workflows/check.yml
@@ -21,7 +21,7 @@ jobs:
           token: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Cache Homebrew
-        uses: actions/cache@8b402f58fbc84540c8b491a91e594a4576fec3d7 # v4
+        uses: actions/cache@cdf6c1fa76f9f475f3d7449005a359c84ca0f306 # v4
         with:
           path: |
             ~/Library/Caches/Homebrew
@@ -74,7 +74,7 @@ jobs:
           ref: ${{ (github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository && github.head_ref) || github.ref }}
 
       - name: Cache Homebrew
-        uses: actions/cache@8b402f58fbc84540c8b491a91e594a4576fec3d7 # v4
+        uses: actions/cache@cdf6c1fa76f9f475f3d7449005a359c84ca0f306 # v4
         with:
           path: |
             ~/Library/Caches/Homebrew

From 7133ea4966688af3bfa9f86d57310c40cf2eb78a Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Tue, 3 Feb 2026 14:46:14 +0800
Subject: [PATCH 02/17] chore(deps): bump github.com/shirou/gopsutil/v4 from
 4.25.12 to 4.26.1 (#406)

Bumps [github.com/shirou/gopsutil/v4](https://github.com/shirou/gopsutil) from 4.25.12 to 4.26.1.
- [Release notes](https://github.com/shirou/gopsutil/releases)
- [Commits](https://github.com/shirou/gopsutil/compare/v4.25.12...v4.26.1)

---
updated-dependencies:
- dependency-name: github.com/shirou/gopsutil/v4
  dependency-version: 4.26.1
  dependency-type: direct:production
  update-type: version-update:semver-minor
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 go.mod | 2 +-
 go.sum | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/go.mod b/go.mod
index 8508e51..48a627c 100644
--- a/go.mod
+++ b/go.mod
@@ -8,7 +8,7 @@ require (
 	github.com/cespare/xxhash/v2 v2.3.0
 	github.com/charmbracelet/bubbletea v1.3.10
 	github.com/charmbracelet/lipgloss v1.1.0
-	github.com/shirou/gopsutil/v4 v4.25.12
+	github.com/shirou/gopsutil/v4 v4.26.1
 	golang.org/x/sync v0.19.0
 )
 
diff --git a/go.sum b/go.sum
index ff620af..baf6360 100644
--- a/go.sum
+++ b/go.sum
@@ -53,8 +53,8 @@ github.com/power-devops/perfstat v0.0.0-20240221224432-82ca36839d55 h1:o4JXh1EVt
 github.com/power-devops/perfstat v0.0.0-20240221224432-82ca36839d55/go.mod h1:OmDBASR4679mdNQnz2pUhc2G8CO2JrUAVFDRBDP/hJE=
 github.com/rivo/uniseg v0.4.7 h1:WUdvkW8uEhrYfLC4ZzdpI2ztxP1I582+49Oc5Mq64VQ=
 github.com/rivo/uniseg v0.4.7/go.mod h1:FN3SvrM+Zdj16jyLfmOkMNblXMcoc8DfTHruCPUcx88=
-github.com/shirou/gopsutil/v4 v4.25.12 h1:e7PvW/0RmJ8p8vPGJH4jvNkOyLmbkXgXW4m6ZPic6CY=
-github.com/shirou/gopsutil/v4 v4.25.12/go.mod h1:EivAfP5x2EhLp2ovdpKSozecVXn1TmuG7SMzs/Wh4PU=
+github.com/shirou/gopsutil/v4 v4.26.1 h1:TOkEyriIXk2HX9d4isZJtbjXbEjf5qyKPAzbzY0JWSo=
+github.com/shirou/gopsutil/v4 v4.26.1/go.mod h1:medLI9/UNAb0dOI9Q3/7yWSqKkj00u+1tgY8nvv41pc=
 github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
 github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
 github.com/tklauser/go-sysconf v0.3.16 h1:frioLaCQSsF5Cy1jgRBrzr6t502KIIwQ0MArYICU0nA=

From 4f3eb0eb62c4fda2a30db78d3dfc85f6b4a5ca83 Mon Sep 17 00:00:00 2001
From: Andrei Murariu <83287213+iamxorum@users.noreply.github.com>
Date: Tue, 3 Feb 2026 08:47:44 +0200
Subject: [PATCH 03/17] bug-fix: uninstall raycast leftovers (#404)

---
 lib/core/app_protection.sh | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/lib/core/app_protection.sh b/lib/core/app_protection.sh
index a270626..bb93abe 100755
--- a/lib/core/app_protection.sh
+++ b/lib/core/app_protection.sh
@@ -1091,6 +1091,32 @@ find_app_files() {
     [[ "$bundle_id" =~ microsoft.*vscode ]] && [[ -d ~/.vscode ]] && files_to_clean+=("$HOME/.vscode")
     [[ "$app_name" =~ Docker ]] && [[ -d ~/.docker ]] && files_to_clean+=("$HOME/.docker")
 
+    # 7. Raycast
+    if [[ "$bundle_id" == "com.raycast.macos" ]]; then
+        local raycast_parents=(
+            "$HOME/Library/Application Support"
+            "$HOME/Library/Application Scripts"
+            "$HOME/Library/Containers"
+        )
+        for parent in "${raycast_parents[@]}"; do
+            [[ -d "$parent" ]] || continue
+            while IFS= read -r -d '' p; do
+                files_to_clean+=("$p")
+            done < <(command find "$parent" -maxdepth 1 -type d -iname "*raycast*" -print0 2> /dev/null)
+        done
+        if [[ -d "$HOME/Library/Caches" ]]; then
+            while IFS= read -r -d '' p; do
+                files_to_clean+=("$p")
+            done < <(command find "$HOME/Library/Caches" -maxdepth 2 -type d -iname "*raycast*" -print0 2> /dev/null)
+        fi
+        local code_storage="$HOME/Library/Application Support/Code/User/globalStorage"
+        if [[ -d "$code_storage" ]]; then
+            while IFS= read -r -d '' p; do
+                files_to_clean+=("$p")
+            done < <(command find "$code_storage" -maxdepth 1 -type d -iname "*raycast*" -print0 2> /dev/null)
+        fi
+    fi
+
     # Output results
     if [[ ${#files_to_clean[@]} -gt 0 ]]; then
         printf '%s\n' "${files_to_clean[@]}"
@@ -1184,6 +1210,13 @@ find_app_system_files() {
         done < <(command find /private/var/db/receipts -maxdepth 1 \( -name "*$bundle_id*" \) -print0 2> /dev/null)
     fi
 
+    # Raycast system-level (*raycast* under /Library/Application Support)
+    if [[ "$bundle_id" == "com.raycast.macos" && -d "/Library/Application Support" ]]; then
+        while IFS= read -r -d '' p; do
+            system_files+=("$p")
+        done < <(command find "/Library/Application Support" -maxdepth 1 -type d -iname "*raycast*" -print0 2> /dev/null)
+    fi
+
     local receipt_files=""
     receipt_files=$(find_app_receipt_files "$bundle_id")
 

From a5c7abd2276eb9bd376e877b2068a3e4064cdc9b Mon Sep 17 00:00:00 2001
From: tw93 <tw93@qq.com>
Date: Tue, 3 Feb 2026 14:53:10 +0800
Subject: [PATCH 04/17] refactor: optimize raycast cleanup code structure

Improve code readability and maintainability:
- Simplify conditional logic with chained operators
- Add clarifying comments for different cleanup scopes
- Rename variables for better semantic clarity
- Maintain consistent style with other app cleanup patterns
---
 lib/core/app_protection.sh | 38 +++++++++++++++++++-------------------
 1 file changed, 19 insertions(+), 19 deletions(-)

diff --git a/lib/core/app_protection.sh b/lib/core/app_protection.sh
index bb93abe..ed930db 100755
--- a/lib/core/app_protection.sh
+++ b/lib/core/app_protection.sh
@@ -1093,28 +1093,28 @@ find_app_files() {
 
     # 7. Raycast
     if [[ "$bundle_id" == "com.raycast.macos" ]]; then
-        local raycast_parents=(
+        # Standard user directories
+        local raycast_dirs=(
             "$HOME/Library/Application Support"
             "$HOME/Library/Application Scripts"
             "$HOME/Library/Containers"
         )
-        for parent in "${raycast_parents[@]}"; do
-            [[ -d "$parent" ]] || continue
-            while IFS= read -r -d '' p; do
+        for dir in "${raycast_dirs[@]}"; do
+            [[ -d "$dir" ]] && while IFS= read -r -d '' p; do
                 files_to_clean+=("$p")
-            done < <(command find "$parent" -maxdepth 1 -type d -iname "*raycast*" -print0 2> /dev/null)
+            done < <(command find "$dir" -maxdepth 1 -type d -iname "*raycast*" -print0 2> /dev/null)
         done
-        if [[ -d "$HOME/Library/Caches" ]]; then
-            while IFS= read -r -d '' p; do
-                files_to_clean+=("$p")
-            done < <(command find "$HOME/Library/Caches" -maxdepth 2 -type d -iname "*raycast*" -print0 2> /dev/null)
-        fi
-        local code_storage="$HOME/Library/Application Support/Code/User/globalStorage"
-        if [[ -d "$code_storage" ]]; then
-            while IFS= read -r -d '' p; do
-                files_to_clean+=("$p")
-            done < <(command find "$code_storage" -maxdepth 1 -type d -iname "*raycast*" -print0 2> /dev/null)
-        fi
+
+        # Cache (deeper search)
+        [[ -d "$HOME/Library/Caches" ]] && while IFS= read -r -d '' p; do
+            files_to_clean+=("$p")
+        done < <(command find "$HOME/Library/Caches" -maxdepth 2 -type d -iname "*raycast*" -print0 2> /dev/null)
+
+        # VSCode extension storage
+        local vscode_global="$HOME/Library/Application Support/Code/User/globalStorage"
+        [[ -d "$vscode_global" ]] && while IFS= read -r -d '' p; do
+            files_to_clean+=("$p")
+        done < <(command find "$vscode_global" -maxdepth 1 -type d -iname "*raycast*" -print0 2> /dev/null)
     fi
 
     # Output results
@@ -1210,9 +1210,9 @@ find_app_system_files() {
         done < <(command find /private/var/db/receipts -maxdepth 1 \( -name "*$bundle_id*" \) -print0 2> /dev/null)
     fi
 
-    # Raycast system-level (*raycast* under /Library/Application Support)
-    if [[ "$bundle_id" == "com.raycast.macos" && -d "/Library/Application Support" ]]; then
-        while IFS= read -r -d '' p; do
+    # Raycast system-level files
+    if [[ "$bundle_id" == "com.raycast.macos" ]]; then
+        [[ -d "/Library/Application Support" ]] && while IFS= read -r -d '' p; do
             system_files+=("$p")
         done < <(command find "/Library/Application Support" -maxdepth 1 -type d -iname "*raycast*" -print0 2> /dev/null)
     fi

From d3206354f6f5da2025a8d9c72e653fdde65827e0 Mon Sep 17 00:00:00 2001
From: tw93 <tw93@qq.com>
Date: Tue, 3 Feb 2026 15:09:06 +0800
Subject: [PATCH 05/17] docs: add Raycast setup instructions to README for
 better user guidance

---
 README.md | 17 ++++++++++++++++-
 1 file changed, 16 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index e73df6b..ace5934 100644
--- a/README.md
+++ b/README.md
@@ -255,7 +255,22 @@ curl -fsSL https://raw.githubusercontent.com/tw93/Mole/main/scripts/setup-quick-
 
 Adds 5 commands: `clean`, `uninstall`, `optimize`, `analyze`, `status`.
 
-Mole automatically detects your terminal, or set `MO_LAUNCHER_APP=<name>` to override. For Raycast users: if this is your first script directory, add it via Raycast Extensions → Add Script Directory, then run "Reload Script Directories".
+### Raycast Setup
+
+After running the script above, **complete these steps in Raycast**:
+
+1. Open Raycast Settings (⌘ + ,)
+2. Go to **Extensions** → **Script Commands**
+3. Click **"Add Script Directory"** (or **"+"**)
+4. Add path: `~/Library/Application Support/Raycast/script-commands`
+5. Search in Raycast for: **"Reload Script Directories"** and run it
+6. Done! Search for `mole`, `clean`, or `optimize` to use the commands
+
+> **Note**: The script creates the commands automatically, but Raycast requires you to manually add the script directory. This is a one-time setup.
+
+### Terminal Detection
+
+Mole automatically detects your terminal app (Warp, Ghostty, Alacritty, Kitty, WezTerm, etc.). To override, set `MO_LAUNCHER_APP=<name>` in your environment.
 
 ## Community Love
 

From bad1c7123183e46de58f1af03114774edf2bab33 Mon Sep 17 00:00:00 2001
From: tw93 <tw93@qq.com>
Date: Tue, 3 Feb 2026 16:37:33 +0800
Subject: [PATCH 06/17] fix: protect Gradle cache from cleanup by default

Gradle build cache (~/.gradle/caches) is now protected by default whitelist,
similar to Maven repository. This prevents unintentional deletion of large
dependency caches that take time and bandwidth to re-download.

- Add ~/.gradle/caches/* and ~/.gradle/daemon/* to DEFAULT_WHITELIST_PATTERNS
- Remove Gradle cleanup from clean_dev_jvm() function
- Users can disable protection via 'mo clean --whitelist' if needed

Fixes #408
---
 lib/clean/dev.sh | 3 +--
 lib/core/base.sh | 2 ++
 2 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/lib/clean/dev.sh b/lib/clean/dev.sh
index 6f441f1..3306164 100644
--- a/lib/clean/dev.sh
+++ b/lib/clean/dev.sh
@@ -207,9 +207,8 @@ clean_dev_mobile() {
     safe_clean ~/.cache/swift-package-manager/* "Swift package manager cache"
 }
 # JVM ecosystem caches.
+# Gradle excluded (default whitelist, like Maven). Remove via: mo clean --whitelist
 clean_dev_jvm() {
-    safe_clean ~/.gradle/caches/* "Gradle caches"
-    safe_clean ~/.gradle/daemon/* "Gradle daemon logs"
     safe_clean ~/.sbt/* "SBT cache"
     safe_clean ~/.ivy2/cache/* "Ivy cache"
 }
diff --git a/lib/core/base.sh b/lib/core/base.sh
index e2149fb..d0f813b 100644
--- a/lib/core/base.sh
+++ b/lib/core/base.sh
@@ -63,6 +63,8 @@ declare -a DEFAULT_WHITELIST_PATTERNS=(
     "$HOME/Library/Caches/ms-playwright*"
     "$HOME/.cache/huggingface*"
     "$HOME/.m2/repository/*"
+    "$HOME/.gradle/caches/*"
+    "$HOME/.gradle/daemon/*"
     "$HOME/.ollama/models/*"
     "$HOME/Library/Caches/com.nssurge.surge-mac/*"
     "$HOME/Library/Application Support/com.nssurge.surge-mac/*"

From 579c9639405bd0ee23d8c7b6e59ed1d95ef383db Mon Sep 17 00:00:00 2001
From: tw93 <tw93@qq.com>
Date: Tue, 3 Feb 2026 17:36:15 +0800
Subject: [PATCH 07/17] uninstall: refine protection flow and menu filtering

---
 lib/core/app_protection.sh | 11 ++++++--
 lib/ui/menu_paginated.sh   |  8 ++++++
 lib/uninstall/batch.sh     | 57 ++++++++++++--------------------------
 3 files changed, 34 insertions(+), 42 deletions(-)

diff --git a/lib/core/app_protection.sh b/lib/core/app_protection.sh
index ed930db..90fa7dd 100755
--- a/lib/core/app_protection.sh
+++ b/lib/core/app_protection.sh
@@ -707,7 +707,13 @@ should_protect_data() {
             ;;
     esac
 
-    # Most apps won't match, return early
+    # Fallback: check against the full DATA_PROTECTED_BUNDLES list
+    for pattern in "${DATA_PROTECTED_BUNDLES[@]}"; do
+        if bundle_matches_pattern "$bundle_id" "$pattern"; then
+            return 0
+        fi
+    done
+
     return 1
 }
 
@@ -772,7 +778,8 @@ should_protect_path() {
     # Matches: .../Library/Group Containers/group.id/...
     if [[ "$path" =~ /Library/Containers/([^/]+) ]] || [[ "$path" =~ /Library/Group\ Containers/([^/]+) ]]; then
         local bundle_id="${BASH_REMATCH[1]}"
-        if should_protect_data "$bundle_id"; then
+        # In uninstall mode, only system components are protected; skip data protection
+        if [[ "${MOLE_UNINSTALL_MODE:-0}" != "1" ]] && should_protect_data "$bundle_id"; then
             return 0
         fi
     fi
diff --git a/lib/ui/menu_paginated.sh b/lib/ui/menu_paginated.sh
index 05316cd..57c2478 100755
--- a/lib/ui/menu_paginated.sh
+++ b/lib/ui/menu_paginated.sh
@@ -657,6 +657,14 @@ paginated_multi_select() {
                 fi
                 ;;
             "SPACE")
+                # In filter mode with active text, treat space as search character
+                if [[ -n "$filter_text" ]]; then
+                    filter_text+=" "
+                    rebuild_view
+                    cursor_pos=0
+                    need_full_redraw=true
+                    continue
+                fi
                 local idx=$((top_index + cursor_pos))
                 if [[ $idx -lt ${#view_indices[@]} ]]; then
                     local real="${view_indices[idx]}"
diff --git a/lib/uninstall/batch.sh b/lib/uninstall/batch.sh
index cba0ee8..9d03af9 100755
--- a/lib/uninstall/batch.sh
+++ b/lib/uninstall/batch.sh
@@ -300,18 +300,15 @@ batch_uninstall_applications() {
     echo -e "${PURPLE_BOLD}Files to be removed:${NC}"
     echo ""
 
-    # Warn if user data is detected.
-    local has_user_data=false
+    # Warn if brew cask apps are present.
+    local has_brew_cask=false
     for detail in "${app_details[@]}"; do
-        IFS='|' read -r _ _ _ _ _ _ has_sensitive_data <<< "$detail"
-        if [[ "$has_sensitive_data" == "true" ]]; then
-            has_user_data=true
-            break
-        fi
+        IFS='|' read -r _ _ _ _ _ _ _ _ is_brew_cask_flag _ <<< "$detail"
+        [[ "$is_brew_cask_flag" == "true" ]] && has_brew_cask=true
     done
 
-    if [[ "$has_user_data" == "true" ]]; then
-        echo -e "${GRAY}${ICON_WARNING}${NC} ${YELLOW}Note: Some apps contain user configurations/themes${NC}"
+    if [[ "$has_brew_cask" == "true" ]]; then
+        echo -e "${GRAY}${ICON_WARNING}${NC} ${YELLOW}Homebrew apps will be fully cleaned (--zap: removes configs & data)${NC}"
         echo ""
     fi
 
@@ -431,6 +428,7 @@ batch_uninstall_applications() {
         local related_files=$(decode_file_list "$encoded_files" "$app_name")
         local system_files=$(decode_file_list "$encoded_system_files" "$app_name")
         local reason=""
+        local suggestion=""
 
         # Show progress for current app
         local brew_tag=""
@@ -567,7 +565,7 @@ batch_uninstall_applications() {
             [[ "$used_brew_successfully" == "true" ]] && ((brew_apps_removed++))
             ((files_cleaned++))
             ((total_items++))
-            success_items+=("$app_name")
+            success_items+=("$app_path")
         else
             if [[ -t 1 ]]; then
                 if [[ ${#app_details[@]} -gt 1 ]]; then
@@ -593,7 +591,6 @@ batch_uninstall_applications() {
     local -a summary_details=()
 
     if [[ $success_count -gt 0 ]]; then
-        local success_list="${success_items[*]}"
         local success_text="app"
         [[ $success_count -gt 1 ]] && success_text="apps"
         local success_line="Removed ${success_count} ${success_text}"
@@ -602,13 +599,15 @@ batch_uninstall_applications() {
         fi
 
         # Format app list with max 3 per line.
-        if [[ -n "$success_list" ]]; then
+        if [[ ${#success_items[@]} -gt 0 ]]; then
             local idx=0
             local is_first_line=true
             local current_line=""
 
-            for app_name in "${success_items[@]}"; do
-                local display_item="${GREEN}${app_name}${NC}"
+            for success_path in "${success_items[@]}"; do
+                local display_name
+                display_name=$(basename "$success_path" .app)
+                local display_item="${GREEN}${display_name}${NC}"
 
                 if ((idx % 3 == 0)); then
                     if [[ -n "$current_line" ]]; then
@@ -709,20 +708,8 @@ batch_uninstall_applications() {
     fi
 
     # Clean up Dock entries for uninstalled apps.
-    if [[ $success_count -gt 0 ]]; then
-        local -a removed_paths=()
-        for detail in "${app_details[@]}"; do
-            IFS='|' read -r app_name app_path _ _ _ _ <<< "$detail"
-            for success_name in "${success_items[@]}"; do
-                if [[ "$success_name" == "$app_name" ]]; then
-                    removed_paths+=("$app_path")
-                    break
-                fi
-            done
-        done
-        if [[ ${#removed_paths[@]} -gt 0 ]]; then
-            remove_apps_from_dock "${removed_paths[@]}" 2> /dev/null || true
-        fi
+    if [[ $success_count -gt 0 && ${#success_items[@]} -gt 0 ]]; then
+        remove_apps_from_dock "${success_items[@]}" 2> /dev/null || true
     fi
 
     _cleanup_sudo_keepalive
@@ -733,18 +720,8 @@ batch_uninstall_applications() {
     if [[ $success_count -gt 0 ]]; then
         local cache_file="$HOME/.cache/mole/app_scan_cache"
         if [[ -f "$cache_file" ]]; then
-            local -a removed_paths=()
-            for detail in "${app_details[@]}"; do
-                IFS='|' read -r app_name app_path _ _ _ _ <<< "$detail"
-                for success_name in "${success_items[@]}"; do
-                    if [[ "$success_name" == "$app_name" ]]; then
-                        removed_paths+=("$app_path")
-                        break
-                    fi
-                done
-            done
-
-            if [[ ${#removed_paths[@]} -gt 0 ]]; then
+            if [[ ${#success_items[@]} -gt 0 ]]; then
+                local -a removed_paths=("${success_items[@]}")
                 local temp_cache
                 temp_cache=$(create_temp_file)
                 local line_removed=false

From 0fb4d32bb6a9b2eb058719a1c8774324804fa171 Mon Sep 17 00:00:00 2001
From: tw93 <tw93@qq.com>
Date: Tue, 3 Feb 2026 20:53:21 +0800
Subject: [PATCH 08/17] fix: improve whitelist pattern validation in cleanup
 tests

---
 tests/manage_whitelist.bats | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/tests/manage_whitelist.bats b/tests/manage_whitelist.bats
index 234f4fb..fdaa659 100644
--- a/tests/manage_whitelist.bats
+++ b/tests/manage_whitelist.bats
@@ -102,16 +102,17 @@ setup() {
 
     run bash --noprofile --norc -c "cd '$PROJECT_ROOT'; printf \$'\\n' | HOME='$HOME' ./mo clean --whitelist"
     [ "$status" -eq 0 ]
-    grep -q "\\.m2/repository" "$whitelist_file"
+    first_pattern=$(grep -v '^[[:space:]]*#' "$whitelist_file" | grep -v '^[[:space:]]*$' | head -n 1)
+    [ -n "$first_pattern" ]
 
     run bash --noprofile --norc -c "cd '$PROJECT_ROOT'; printf \$' \\n' | HOME='$HOME' ./mo clean --whitelist"
     [ "$status" -eq 0 ]
-    run grep -q "\\.m2/repository" "$whitelist_file"
+    run grep -Fxq "$first_pattern" "$whitelist_file"
     [ "$status" -eq 1 ]
 
     run bash --noprofile --norc -c "cd '$PROJECT_ROOT'; printf \$'\\n' | HOME='$HOME' ./mo clean --whitelist"
     [ "$status" -eq 0 ]
-    run grep -q "\\.m2/repository" "$whitelist_file"
+    run grep -Fxq "$first_pattern" "$whitelist_file"
     [ "$status" -eq 1 ]
 }
 

From a4e084a4edb1d603c115766af088f4f3fbf7a0e2 Mon Sep 17 00:00:00 2001
From: tw93 <tw93@qq.com>
Date: Wed, 4 Feb 2026 16:17:36 +0800
Subject: [PATCH 09/17] feat: improve app cleanup with orphaned LaunchAgent
 detection

New features:
- Add orphaned LaunchAgent/LaunchDaemon detection with 5-layer verification
  - Layer 1: Check if program path exists
  - Layer 2: Verify AssociatedBundleIdentifiers via mdfind
  - Layer 3: Check Application Support directory activity (7 days)
  - Layer 4: Fuzzy match app name in /Applications
  - Layer 5: Special handling for PrivilegedHelperTools
- Only process user-level ~/Library/LaunchAgents (safer than system-level)
- Unload agent before removal using launchctl

Bug fixes:
- Handle paths with spaces correctly in orphaned_app_data cleanup
  - Add nullglob state management to prevent word splitting
  - Use IFS=$'\n' for proper array iteration
- Only count successful deletions (check safe_clean return value)

Tests:
- Add 4 new tests for is_launch_item_orphaned edge cases
- Add tests for space handling and deletion count accuracy
---
 bin/clean.sh          |   1 +
 lib/clean/apps.sh     | 216 ++++++++++++++++++++++++++++++++-
 tests/clean_apps.bats | 269 +++++++++++++++++++++++++++++++++++++++++-
 3 files changed, 479 insertions(+), 7 deletions(-)

diff --git a/bin/clean.sh b/bin/clean.sh
index 6d11602..36d114f 100755
--- a/bin/clean.sh
+++ b/bin/clean.sh
@@ -970,6 +970,7 @@ perform_cleanup() {
     start_section "Uninstalled app data"
     clean_orphaned_app_data
     clean_orphaned_system_services
+    clean_orphaned_launch_agents
     end_section
 
     # ===== 13. Apple Silicon optimizations =====
diff --git a/lib/clean/apps.sh b/lib/clean/apps.sh
index e9f193c..adedcae 100644
--- a/lib/clean/apps.sh
+++ b/lib/clean/apps.sh
@@ -1,6 +1,8 @@
 #!/bin/bash
 # Application Data Cleanup Module
 set -euo pipefail
+
+readonly ORPHAN_AGE_THRESHOLD=${ORPHAN_AGE_THRESHOLD:-${MOLE_ORPHAN_AGE_DAYS:-60}}
 # Args: $1=target_dir, $2=label
 clean_ds_store_tree() {
     local target="$1"
@@ -282,9 +284,19 @@ clean_orphaned_app_data() {
             file_patterns+=("$base_path/$pat")
         done
         if [[ ${#file_patterns[@]} -gt 0 ]]; then
+            local _nullglob_state
+            _nullglob_state=$(shopt -p nullglob || true)
+            shopt -s nullglob
             for item_path in "${file_patterns[@]}"; do
                 local iteration_count=0
-                for match in $item_path; do
+                local old_ifs=$IFS
+                IFS=$'\n'
+                local -a matches=($item_path)
+                IFS=$old_ifs
+                if [[ ${#matches[@]} -eq 0 ]]; then
+                    continue
+                fi
+                for match in "${matches[@]}"; do
                     [[ -e "$match" ]] || continue
                     ((iteration_count++))
                     if [[ $iteration_count -gt $MOLE_MAX_ORPHAN_ITERATIONS ]]; then
@@ -299,12 +311,14 @@ clean_orphaned_app_data() {
                         if [[ -z "$size_kb" || "$size_kb" == "0" ]]; then
                             continue
                         fi
-                        safe_clean "$match" "Orphaned $label: $bundle_id"
-                        ((orphaned_count++))
-                        ((total_orphaned_kb += size_kb))
+                        if safe_clean "$match" "Orphaned $label: $bundle_id"; then
+                            ((orphaned_count++))
+                            ((total_orphaned_kb += size_kb))
+                        fi
                     fi
                 done
             done
+            eval "$_nullglob_state"
         fi
     done
     stop_section_spinner
@@ -517,3 +531,197 @@ clean_orphaned_system_services() {
     fi
 
 }
+
+# ============================================================================
+# Orphaned LaunchAgent/LaunchDaemon Cleanup (Generic Detection)
+# ============================================================================
+
+# Extract program path from plist (supports both ProgramArguments and Program)
+_extract_program_path() {
+    local plist="$1"
+    local program=""
+
+    program=$(plutil -extract ProgramArguments.0 raw "$plist" 2> /dev/null)
+    if [[ -z "$program" ]]; then
+        program=$(plutil -extract Program raw "$plist" 2> /dev/null)
+    fi
+
+    echo "$program"
+}
+
+# Extract associated bundle identifier from plist
+_extract_associated_bundle() {
+    local plist="$1"
+    local associated=""
+
+    # Try array format first
+    associated=$(plutil -extract AssociatedBundleIdentifiers.0 raw "$plist" 2> /dev/null)
+    if [[ -z "$associated" ]] || [[ "$associated" == "1" ]]; then
+        # Try string format
+        associated=$(plutil -extract AssociatedBundleIdentifiers raw "$plist" 2> /dev/null)
+        # Filter out dict/array markers
+        if [[ "$associated" == "{"* ]] || [[ "$associated" == "["* ]]; then
+            associated=""
+        fi
+    fi
+
+    echo "$associated"
+}
+
+# Check if a LaunchAgent/LaunchDaemon is orphaned using multi-layer verification
+# Returns 0 if orphaned, 1 if not orphaned
+is_launch_item_orphaned() {
+    local plist="$1"
+
+    # Layer 1: Check if program path exists
+    local program=$(_extract_program_path "$plist")
+
+    # No program path - skip (not a standard launch item)
+    [[ -z "$program" ]] && return 1
+
+    # Program exists -> not orphaned
+    [[ -e "$program" ]] && return 1
+
+    # Layer 2: Check AssociatedBundleIdentifiers
+    local associated=$(_extract_associated_bundle "$plist")
+    if [[ -n "$associated" ]]; then
+        # Check if associated app exists via mdfind
+        if run_with_timeout 2 mdfind "kMDItemCFBundleIdentifier == '$associated'" 2> /dev/null | head -1 | grep -q .; then
+            return 1 # Associated app found -> not orphaned
+        fi
+
+        # Extract vendor name from bundle ID (com.vendor.app -> vendor)
+        local vendor=$(echo "$associated" | cut -d'.' -f2)
+        if [[ -n "$vendor" ]] && [[ ${#vendor} -ge 3 ]]; then
+            # Check if any app from this vendor exists
+            if find /Applications ~/Applications -maxdepth 2 -iname "*${vendor}*" -type d 2> /dev/null | grep -iq "\.app"; then
+                return 1 # Vendor app exists -> not orphaned
+            fi
+        fi
+    fi
+
+    # Layer 3: Check Application Support directory activity
+    if [[ "$program" =~ /Library/Application\ Support/([^/]+)/ ]]; then
+        local app_support_name="${BASH_REMATCH[1]}"
+
+        # Check both user and system Application Support
+        for base in "$HOME/Library/Application Support" "/Library/Application Support"; do
+            local support_path="$base/$app_support_name"
+            if [[ -d "$support_path" ]]; then
+                # Check if there are files modified in last 7 days (active usage)
+                local recent_file=$(find "$support_path" -type f -mtime -7 2> /dev/null | head -1)
+                if [[ -n "$recent_file" ]]; then
+                    return 1 # Active Application Support -> not orphaned
+                fi
+            fi
+        done
+    fi
+
+    # Layer 4: Check if app name from program path exists
+    if [[ "$program" =~ /Applications/([^/]+)\.app/ ]]; then
+        local app_name="${BASH_REMATCH[1]}"
+        # Look for apps with similar names (case-insensitive)
+        if find /Applications ~/Applications -maxdepth 2 -iname "*${app_name}*" -type d 2> /dev/null | grep -iq "\.app"; then
+            return 1 # Similar app exists -> not orphaned
+        fi
+    fi
+
+    # Layer 5: PrivilegedHelper special handling
+    if [[ "$program" =~ ^/Library/PrivilegedHelperTools/ ]]; then
+        local filename=$(basename "$plist")
+        local bundle_id="${filename%.plist}"
+
+        # Extract app hint from bundle ID (com.vendor.app.helper -> vendor)
+        local app_hint=$(echo "$bundle_id" | sed 's/com\.//; s/\..*helper.*//')
+
+        if [[ -n "$app_hint" ]] && [[ ${#app_hint} -ge 3 ]]; then
+            # Look for main app
+            if find /Applications ~/Applications -maxdepth 2 -iname "*${app_hint}*" -type d 2> /dev/null | grep -iq "\.app"; then
+                return 1 # Helper's main app exists -> not orphaned
+            fi
+        fi
+    fi
+
+    # All checks failed -> likely orphaned
+    return 0
+}
+
+# Clean orphaned user-level LaunchAgents
+# Only processes ~/Library/LaunchAgents (safer than system-level)
+clean_orphaned_launch_agents() {
+    local launch_agents_dir="$HOME/Library/LaunchAgents"
+
+    [[ ! -d "$launch_agents_dir" ]] && return 0
+
+    start_section_spinner "Scanning orphaned launch agents..."
+
+    local -a orphaned_items=()
+    local total_orphaned_kb=0
+
+    # Scan user LaunchAgents
+    while IFS= read -r -d '' plist; do
+        local filename=$(basename "$plist")
+
+        # Skip Apple's LaunchAgents
+        [[ "$filename" == com.apple.* ]] && continue
+
+        local bundle_id="${filename%.plist}"
+
+        # Check if orphaned using multi-layer verification
+        if is_launch_item_orphaned "$plist"; then
+            local size_kb=$(get_path_size_kb "$plist")
+            orphaned_items+=("$bundle_id|$plist")
+            ((total_orphaned_kb += size_kb))
+        fi
+    done < <(find "$launch_agents_dir" -maxdepth 1 -name "*.plist" -print0 2> /dev/null)
+
+    stop_section_spinner
+
+    local orphaned_count=${#orphaned_items[@]}
+
+    if [[ $orphaned_count -eq 0 ]]; then
+        return 0
+    fi
+
+    # Clean the orphaned items automatically
+    local removed_count=0
+    local dry_run_count=0
+    local is_dry_run=false
+    if [[ "${MOLE_DRY_RUN:-0}" == "1" ]]; then
+        is_dry_run=true
+    fi
+    for item in "${orphaned_items[@]}"; do
+        IFS='|' read -r bundle_id plist_path <<< "$item"
+
+        if [[ "$is_dry_run" == "true" ]]; then
+            ((dry_run_count++))
+            log_operation "clean" "DRY_RUN" "$plist_path" "orphaned launch agent"
+            continue
+        fi
+
+        # Try to unload first (if currently loaded)
+        launchctl unload "$plist_path" 2> /dev/null || true
+
+        # Remove the plist file
+        if safe_remove "$plist_path" false; then
+            ((removed_count++))
+            log_operation "clean" "REMOVED" "$plist_path" "orphaned launch agent"
+        else
+            log_operation "clean" "FAILED" "$plist_path" "permission denied"
+        fi
+    done
+
+    if [[ "$is_dry_run" == "true" ]]; then
+        if [[ $dry_run_count -gt 0 ]]; then
+            local cleaned_mb=$(echo "$total_orphaned_kb" | awk '{printf "%.1f", $1/1024}')
+            echo "  ${YELLOW}${ICON_DRY_RUN}${NC} Would remove $dry_run_count orphaned launch agent(s), ${cleaned_mb}MB"
+            note_activity
+        fi
+    else
+        if [[ $removed_count -gt 0 ]]; then
+            local cleaned_mb=$(echo "$total_orphaned_kb" | awk '{printf "%.1f", $1/1024}')
+            echo "  ${GREEN}${ICON_SUCCESS}${NC} Removed $removed_count orphaned launch agent(s), ${cleaned_mb}MB"
+            note_activity
+        fi
+    fi
+}
diff --git a/tests/clean_apps.bats b/tests/clean_apps.bats
index 8de3f71..6308f0e 100644
--- a/tests/clean_apps.bats
+++ b/tests/clean_apps.bats
@@ -80,15 +80,137 @@ EOF
 set -euo pipefail
 source "$PROJECT_ROOT/lib/core/common.sh"
 source "$PROJECT_ROOT/lib/clean/apps.sh"
-ls() { return 1; }
-stop_section_spinner() { :; }
+rm -rf "$HOME/Library/Caches"
 clean_orphaned_app_data
 EOF
 
     [ "$status" -eq 0 ]
-    [[ "$output" == *"Skipped: No permission"* ]]
+    [[ "$output" == *"No permission"* ]]
 }
 
+@test "clean_orphaned_app_data handles paths with spaces correctly" {
+    run env HOME="$HOME" PROJECT_ROOT="$PROJECT_ROOT" bash --noprofile --norc <<'EOF'
+set -euo pipefail
+source "$PROJECT_ROOT/lib/core/common.sh"
+source "$PROJECT_ROOT/lib/clean/apps.sh"
+
+# Mock scan_installed_apps - return empty (no installed apps)
+scan_installed_apps() {
+    : > "$1"
+}
+
+# Mock mdfind to return empty (no app found)
+mdfind() {
+    return 0
+}
+
+# Ensure local function mock works even if timeout/gtimeout is installed
+run_with_timeout() { shift; "$@"; }
+
+# Mock safe_clean (normally from bin/clean.sh)
+safe_clean() {
+    rm -rf "$1"
+    return 0
+}
+
+# Create required Library structure for permission check
+mkdir -p "$HOME/Library/Caches"
+
+# Create test structure with spaces in path (old modification time: 61 days ago)
+mkdir -p "$HOME/Library/Saved Application State/com.test.orphan.savedState"
+# Create a file with some content so directory size > 0
+echo "test data" > "$HOME/Library/Saved Application State/com.test.orphan.savedState/data.plist"
+# Set modification time to 61 days ago (older than 60-day threshold)
+touch -t "$(date -v-61d +%Y%m%d%H%M.%S 2>/dev/null || date -d '61 days ago' +%Y%m%d%H%M.%S)" "$HOME/Library/Saved Application State/com.test.orphan.savedState" 2>/dev/null || true
+
+# Disable spinner for test
+start_section_spinner() { :; }
+stop_section_spinner() { :; }
+
+# Run cleanup
+clean_orphaned_app_data
+
+# Verify path with spaces was handled correctly (not split into multiple paths)
+if [[ -d "$HOME/Library/Saved Application State/com.test.orphan.savedState" ]]; then
+    echo "ERROR: Orphaned savedState not deleted"
+    exit 1
+else
+    echo "SUCCESS: Orphaned savedState deleted correctly"
+fi
+EOF
+
+    [ "$status" -eq 0 ]
+    [[ "$output" == *"SUCCESS"* ]]
+}
+
+@test "clean_orphaned_app_data only counts successful deletions" {
+    run env HOME="$HOME" PROJECT_ROOT="$PROJECT_ROOT" bash --noprofile --norc <<'EOF'
+set -euo pipefail
+source "$PROJECT_ROOT/lib/core/common.sh"
+source "$PROJECT_ROOT/lib/clean/apps.sh"
+
+# Mock scan_installed_apps - return empty
+scan_installed_apps() {
+    : > "$1"
+}
+
+# Mock mdfind to return empty (no app found)
+mdfind() {
+    return 0
+}
+
+# Ensure local function mock works even if timeout/gtimeout is installed
+run_with_timeout() { shift; "$@"; }
+
+# Create required Library structure for permission check
+mkdir -p "$HOME/Library/Caches"
+
+# Create test files (old modification time: 61 days ago)
+mkdir -p "$HOME/Library/Caches/com.test.orphan1"
+mkdir -p "$HOME/Library/Caches/com.test.orphan2"
+# Create files with content so size > 0
+echo "data1" > "$HOME/Library/Caches/com.test.orphan1/data"
+echo "data2" > "$HOME/Library/Caches/com.test.orphan2/data"
+# Set modification time to 61 days ago
+touch -t "$(date -v-61d +%Y%m%d%H%M.%S 2>/dev/null || date -d '61 days ago' +%Y%m%d%H%M.%S)" "$HOME/Library/Caches/com.test.orphan1" 2>/dev/null || true
+touch -t "$(date -v-61d +%Y%m%d%H%M.%S 2>/dev/null || date -d '61 days ago' +%Y%m%d%H%M.%S)" "$HOME/Library/Caches/com.test.orphan2" 2>/dev/null || true
+
+# Mock safe_clean to fail on first item, succeed on second
+safe_clean() {
+    if [[ "$1" == *"orphan1"* ]]; then
+        return 1  # Fail
+    else
+        rm -rf "$1"
+        return 0  # Succeed
+    fi
+}
+
+# Disable spinner
+start_section_spinner() { :; }
+stop_section_spinner() { :; }
+
+# Run cleanup
+clean_orphaned_app_data
+
+# Verify first item still exists (safe_clean failed)
+if [[ -d "$HOME/Library/Caches/com.test.orphan1" ]]; then
+    echo "PASS: Failed deletion preserved"
+fi
+
+# Verify second item deleted
+if [[ ! -d "$HOME/Library/Caches/com.test.orphan2" ]]; then
+    echo "PASS: Successful deletion removed"
+fi
+
+# Check that output shows correct count (only 1, not 2)
+EOF
+
+    [ "$status" -eq 0 ]
+    [[ "$output" == *"PASS: Failed deletion preserved"* ]]
+    [[ "$output" == *"PASS: Successful deletion removed"* ]]
+}
+
+
 @test "is_critical_system_component matches known system services" {
     run bash --noprofile --norc <<'EOF'
 set -euo pipefail
@@ -160,3 +282,144 @@ EOF
     [[ "$output" != *"rm-called"* ]]
     [[ "$output" != *"launchctl-called"* ]]
 }
+
+@test "is_launch_item_orphaned detects orphan when program missing" {
+    run env HOME="$HOME" PROJECT_ROOT="$PROJECT_ROOT" bash --noprofile --norc <<'EOF'
+set -euo pipefail
+source "$PROJECT_ROOT/lib/core/common.sh"
+source "$PROJECT_ROOT/lib/clean/apps.sh"
+
+tmp_dir="$(mktemp -d)"
+tmp_plist="$tmp_dir/com.test.orphan.plist"
+
+cat > "$tmp_plist" << 'PLIST'
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.test.orphan</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>/nonexistent/app/program</string>
+    </array>
+</dict>
+</plist>
+PLIST
+
+run_with_timeout() { shift; "$@"; }
+
+if is_launch_item_orphaned "$tmp_plist"; then
+    echo "orphan"
+fi
+
+rm -rf "$tmp_dir"
+EOF
+
+    [ "$status" -eq 0 ]
+    [[ "$output" == *"orphan"* ]]
+}
+
+@test "is_launch_item_orphaned protects when program exists" {
+    run env HOME="$HOME" PROJECT_ROOT="$PROJECT_ROOT" bash --noprofile --norc <<'EOF'
+set -euo pipefail
+source "$PROJECT_ROOT/lib/core/common.sh"
+source "$PROJECT_ROOT/lib/clean/apps.sh"
+
+tmp_dir="$(mktemp -d)"
+tmp_plist="$tmp_dir/com.test.active.plist"
+tmp_program="$tmp_dir/program"
+touch "$tmp_program"
+
+cat > "$tmp_plist" << PLIST
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.test.active</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>$tmp_program</string>
+    </array>
+</dict>
+</plist>
+PLIST
+
+run_with_timeout() { shift; "$@"; }
+
+if is_launch_item_orphaned "$tmp_plist"; then
+    echo "orphan"
+else
+    echo "not-orphan"
+fi
+
+rm -rf "$tmp_dir"
+EOF
+
+    [ "$status" -eq 0 ]
+    [[ "$output" == *"not-orphan"* ]]
+}
+
+@test "is_launch_item_orphaned protects when app support active" {
+    run env HOME="$HOME" PROJECT_ROOT="$PROJECT_ROOT" bash --noprofile --norc <<'EOF'
+set -euo pipefail
+source "$PROJECT_ROOT/lib/core/common.sh"
+source "$PROJECT_ROOT/lib/clean/apps.sh"
+
+tmp_dir="$(mktemp -d)"
+tmp_plist="$tmp_dir/com.test.appsupport.plist"
+
+mkdir -p "$HOME/Library/Application Support/TestApp"
+touch "$HOME/Library/Application Support/TestApp/recent.txt"
+
+cat > "$tmp_plist" << 'PLIST'
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.test.appsupport</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>$HOME/Library/Application Support/TestApp/Current/app</string>
+    </array>
+</dict>
+</plist>
+PLIST
+
+run_with_timeout() { shift; "$@"; }
+
+if is_launch_item_orphaned "$tmp_plist"; then
+    echo "orphan"
+else
+    echo "not-orphan"
+fi
+
+rm -rf "$tmp_dir"
+rm -rf "$HOME/Library/Application Support/TestApp"
+EOF
+
+    [ "$status" -eq 0 ]
+    [[ "$output" == *"not-orphan"* ]]
+}
+
+@test "clean_orphaned_launch_agents skips when no orphans" {
+    run env HOME="$HOME" PROJECT_ROOT="$PROJECT_ROOT" bash --noprofile --norc <<'EOF'
+set -euo pipefail
+source "$PROJECT_ROOT/lib/core/common.sh"
+source "$PROJECT_ROOT/lib/clean/apps.sh"
+
+mkdir -p "$HOME/Library/LaunchAgents"
+
+start_section_spinner() { :; }
+stop_section_spinner() { :; }
+note_activity() { :; }
+get_path_size_kb() { echo "1"; }
+run_with_timeout() { shift; "$@"; }
+
+clean_orphaned_launch_agents
+EOF
+
+    [ "$status" -eq 0 ]
+}

From 0fbf2661c8e8d133df5468d7f71d83d57092f90e Mon Sep 17 00:00:00 2001
From: tw93 <tw93@qq.com>
Date: Wed, 4 Feb 2026 16:18:06 +0800
Subject: [PATCH 10/17] perf: optimize system cleanup by merging find
 operations

Performance improvements:
- Merge 3 separate find operations into 1 for /Library/Caches
  - Combine *.cache, *.tmp, *.log patterns in single scan
  - Reduces filesystem traversal overhead
- Merge 2 find operations into 1 for /private/var/log
  - Combine *.log and *.gz patterns
- Optimize diagnostics cleanup with single combined scan
  - Merge Special, Persist, and tracev3 patterns
  - Reduces redundant directory traversal
- Use find -delete for batch removal of memory exception reports
  - More efficient than iterative removal for large file counts
  - Add summary logging to operations.log

UI improvements:
- Add granular spinner messages for each cleanup stage
- Separate diagnostic logs and power logs output for clarity
- Add progress feedback during Time Machine status check

Tests:
- Update sudo mock functions to support new combined find patterns
- Verify find -delete usage for memory exception cleanup
- Update assertions to match optimized implementation
---
 lib/clean/system.sh                 | 107 ++++++++++++++++++++++------
 tests/clean_system_maintenance.bats |  61 ++++++++++++++--
 2 files changed, 141 insertions(+), 27 deletions(-)

diff --git a/lib/clean/system.sh b/lib/clean/system.sh
index 086c51c..13be78f 100644
--- a/lib/clean/system.sh
+++ b/lib/clean/system.sh
@@ -5,19 +5,47 @@ set -euo pipefail
 clean_deep_system() {
     stop_section_spinner
     local cache_cleaned=0
-    safe_sudo_find_delete "/Library/Caches" "*.cache" "$MOLE_TEMP_FILE_AGE_DAYS" "f" && cache_cleaned=1 || true
-    safe_sudo_find_delete "/Library/Caches" "*.tmp" "$MOLE_TEMP_FILE_AGE_DAYS" "f" && cache_cleaned=1 || true
-    safe_sudo_find_delete "/Library/Caches" "*.log" "$MOLE_LOG_AGE_DAYS" "f" && cache_cleaned=1 || true
+    # Optimized: Single pass for /Library/Caches (3 patterns in 1 scan)
+    if sudo test -d "/Library/Caches" 2> /dev/null; then
+        while IFS= read -r -d '' file; do
+            if should_protect_path "$file"; then
+                continue
+            fi
+            if safe_sudo_remove "$file"; then
+                cache_cleaned=1
+            fi
+        done < <(sudo find "/Library/Caches" -maxdepth 5 -type f \( \
+            \( -name "*.cache" -mtime "+$MOLE_TEMP_FILE_AGE_DAYS" \) -o \
+            \( -name "*.tmp" -mtime "+$MOLE_TEMP_FILE_AGE_DAYS" \) -o \
+            \( -name "*.log" -mtime "+$MOLE_LOG_AGE_DAYS" \) \
+            \) -print0 2> /dev/null || true)
+    fi
     [[ $cache_cleaned -eq 1 ]] && log_success "System caches"
+    start_section_spinner "Cleaning system temporary files..."
     local tmp_cleaned=0
     safe_sudo_find_delete "/private/tmp" "*" "${MOLE_TEMP_FILE_AGE_DAYS}" "f" && tmp_cleaned=1 || true
     safe_sudo_find_delete "/private/var/tmp" "*" "${MOLE_TEMP_FILE_AGE_DAYS}" "f" && tmp_cleaned=1 || true
+    stop_section_spinner
     [[ $tmp_cleaned -eq 1 ]] && log_success "System temp files"
+    start_section_spinner "Cleaning system crash reports..."
     safe_sudo_find_delete "/Library/Logs/DiagnosticReports" "*" "$MOLE_CRASH_REPORT_AGE_DAYS" "f" || true
+    stop_section_spinner
     log_success "System crash reports"
-    safe_sudo_find_delete "/private/var/log" "*.log" "$MOLE_LOG_AGE_DAYS" "f" || true
-    safe_sudo_find_delete "/private/var/log" "*.gz" "$MOLE_LOG_AGE_DAYS" "f" || true
+    start_section_spinner "Cleaning system logs..."
+    # Optimized: Single pass for /private/var/log (2 patterns in 1 scan)
+    if sudo test -d "/private/var/log" 2> /dev/null; then
+        while IFS= read -r -d '' file; do
+            if should_protect_path "$file"; then
+                continue
+            fi
+            safe_sudo_remove "$file" || true
+        done < <(sudo find "/private/var/log" -maxdepth 5 -type f \( \
+            -name "*.log" -o -name "*.gz" \
+            \) -mtime "+$MOLE_LOG_AGE_DAYS" -print0 2> /dev/null || true)
+    fi
+    stop_section_spinner
     log_success "System logs"
+    start_section_spinner "Scanning system library updates..."
     if [[ -d "/Library/Updates" && ! -L "/Library/Updates" ]]; then
         local updates_cleaned=0
         while IFS= read -r -d '' item; do
@@ -34,8 +62,12 @@ clean_deep_system() {
                 ((updates_cleaned++))
             fi
         done < <(find /Library/Updates -mindepth 1 -maxdepth 1 -print0 2> /dev/null || true)
+        stop_section_spinner
         [[ $updates_cleaned -gt 0 ]] && log_success "System library updates"
+    else
+        stop_section_spinner
     fi
+    start_section_spinner "Scanning macOS installer files..."
     if [[ -d "/macOS Install Data" ]]; then
         local mtime=$(get_file_mtime "/macOS Install Data")
         local age_days=$((($(get_epoch_seconds) - mtime) / 86400))
@@ -81,6 +113,7 @@ clean_deep_system() {
             fi
         fi
     done
+    stop_section_spinner
     [[ $installer_cleaned -gt 0 ]] && debug_log "Cleaned $installer_cleaned macOS installer(s)"
     start_section_spinner "Scanning system caches..."
     local code_sign_cleaned=0
@@ -107,23 +140,54 @@ clean_deep_system() {
     stop_section_spinner
     [[ $code_sign_cleaned -gt 0 ]] && log_success "Browser code signature caches, $code_sign_cleaned items"
 
-    start_section_spinner "Cleaning system diagnostic logs..."
-    local diag_cleaned=0
-    safe_sudo_find_delete "/private/var/db/diagnostics/Special" "*" "$MOLE_LOG_AGE_DAYS" "f" && diag_cleaned=1 || true
-    safe_sudo_find_delete "/private/var/db/diagnostics/Persist" "*" "$MOLE_LOG_AGE_DAYS" "f" && diag_cleaned=1 || true
-    safe_sudo_find_delete "/private/var/db/DiagnosticPipeline" "*" "$MOLE_LOG_AGE_DAYS" "f" && diag_cleaned=1 || true
-    safe_sudo_find_delete "/private/var/db/powerlog" "*" "$MOLE_LOG_AGE_DAYS" "f" && diag_cleaned=1 || true
-    safe_sudo_find_delete "/private/var/db/reportmemoryexception/MemoryLimitViolations" "*" "30" "f" && diag_cleaned=1 || true
-    stop_section_spinner
+    # Optimized: Single pass for diagnostics directory (Special + Persist + tracev3)
+    # Replaces 4 separate find operations with 1 combined operation
+    local diag_base="/private/var/db/diagnostics"
+    if sudo test -d "$diag_base" 2> /dev/null; then
+        while IFS= read -r -d '' file; do
+            if should_protect_path "$file"; then
+                continue
+            fi
+            safe_sudo_remove "$file" || true
+        done < <(sudo find "$diag_base" -maxdepth 5 -type f \( \
+            \( -mtime "+$MOLE_LOG_AGE_DAYS" \) -o \
+            \( -name "*.tracev3" -mtime +30 \) \
+            \) -print0 2> /dev/null || true)
+    fi
+    safe_sudo_find_delete "/private/var/db/DiagnosticPipeline" "*" "$MOLE_LOG_AGE_DAYS" "f" || true
+    log_success "System diagnostic logs"
+    safe_sudo_find_delete "/private/var/db/powerlog" "*" "$MOLE_LOG_AGE_DAYS" "f" || true
+    log_success "Power logs"
+    start_section_spinner "Cleaning memory exception reports..."
+    local mem_reports_dir="/private/var/db/reportmemoryexception/MemoryLimitViolations"
+    if sudo test -d "$mem_reports_dir" 2> /dev/null; then
+        # Count and size old files before deletion
+        local file_count=0
+        local total_size_kb=0
+        while IFS= read -r -d '' file; do
+            ((file_count++))
+            local file_size
+            file_size=$(sudo stat -f%z "$file" 2> /dev/null || echo "0")
+            ((total_size_kb += file_size / 1024))
+        done < <(sudo find "$mem_reports_dir" -type f -mtime +30 -print0 2> /dev/null || true)
 
-    [[ $diag_cleaned -eq 1 ]] && log_success "System diagnostic logs"
-
-    start_section_spinner "Cleaning diagnostic trace logs..."
-    local trace_cleaned=0
-    safe_sudo_find_delete "/private/var/db/diagnostics/Persist" "*.tracev3" "30" "f" && trace_cleaned=1 || true
-    safe_sudo_find_delete "/private/var/db/diagnostics/Special" "*.tracev3" "30" "f" && trace_cleaned=1 || true
+        # For directories with many files, use find -delete for performance
+        if [[ "$file_count" -gt 0 ]]; then
+            if [[ "${MOLE_DRY_RUN:-0}" != "1" ]]; then
+                sudo find "$mem_reports_dir" -type f -mtime +30 -delete 2> /dev/null || true
+                # Log summary to operations.log
+                if oplog_enabled && [[ "$total_size_kb" -gt 0 ]]; then
+                    local size_human
+                    size_human=$(bytes_to_human "$((total_size_kb * 1024))")
+                    log_operation "[clean] REMOVED $mem_reports_dir ($file_count files, $size_human)"
+                fi
+            else
+                log_info "[DRY-RUN] Would remove $file_count old memory exception reports ($total_size_kb KB)"
+            fi
+        fi
+    fi
     stop_section_spinner
-    [[ $trace_cleaned -eq 1 ]] && log_success "System diagnostic trace logs"
+    log_success "Memory exception reports"
 }
 # Incomplete Time Machine backups.
 clean_time_machine_failed_backups() {
@@ -304,15 +368,18 @@ clean_local_snapshots() {
         return 0
     fi
 
+    start_section_spinner "Checking Time Machine status..."
     local rc_running=0
     tm_is_running || rc_running=$?
 
     if [[ $rc_running -eq 2 ]]; then
+        stop_section_spinner
         echo -e "  ${YELLOW}!${NC} Could not determine Time Machine status; skipping snapshot check"
         return 0
     fi
 
     if [[ $rc_running -eq 0 ]]; then
+        stop_section_spinner
         echo -e "  ${YELLOW}!${NC} Time Machine is active; skipping snapshot check"
         return 0
     fi
diff --git a/tests/clean_system_maintenance.bats b/tests/clean_system_maintenance.bats
index 97f2b5a..46f52ed 100644
--- a/tests/clean_system_maintenance.bats
+++ b/tests/clean_system_maintenance.bats
@@ -28,7 +28,23 @@ CALL_LOG="$HOME/system_calls.log"
 source "$PROJECT_ROOT/lib/core/common.sh"
 source "$PROJECT_ROOT/lib/clean/system.sh"
 
-sudo() { return 0; }
+sudo() {
+    if [[ "$1" == "test" ]]; then
+        return 0
+    fi
+    if [[ "$1" == "find" ]]; then
+        case "$2" in
+            /Library/Caches) printf '%s\0' "/Library/Caches/test.log" ;;
+            /private/var/log) printf '%s\0' "/private/var/log/system.log" ;;
+        esac
+        return 0
+    fi
+    if [[ "$1" == "stat" ]]; then
+        echo "0"
+        return 0
+    fi
+    return 0
+}
 safe_sudo_find_delete() {
     echo "safe_sudo_find_delete:$1:$2" >> "$CALL_LOG"
     return 0
@@ -562,11 +578,24 @@ CALL_LOG="$HOME/memory_exception_calls.log"
 source "$PROJECT_ROOT/lib/core/common.sh"
 source "$PROJECT_ROOT/lib/clean/system.sh"
 
-sudo() { return 0; }
-safe_sudo_find_delete() {
-    echo "safe_sudo_find_delete:$1:$2:$3:$4" >> "$CALL_LOG"
+sudo() {
+    if [[ "$1" == "test" ]]; then
+        return 0
+    fi
+    if [[ "$1" == "find" ]]; then
+        echo "sudo_find:$*" >> "$CALL_LOG"
+        if [[ "$2" == "/private/var/db/reportmemoryexception/MemoryLimitViolations" && "$*" != *"-delete"* ]]; then
+            printf '%s\0' "/private/var/db/reportmemoryexception/MemoryLimitViolations/report.bin"
+        fi
+        return 0
+    fi
+    if [[ "$1" == "stat" ]]; then
+        echo "1024"
+        return 0
+    fi
     return 0
 }
+safe_sudo_find_delete() { return 0; }
 safe_sudo_remove() { return 0; }
 log_success() { :; }
 is_sip_enabled() { return 1; }
@@ -579,7 +608,8 @@ EOF
 
     [ "$status" -eq 0 ]
     [[ "$output" == *"reportmemoryexception/MemoryLimitViolations"* ]]
-    [[ "$output" == *":30:"* ]]  # 30-day retention
+    [[ "$output" == *"-mtime +30"* ]]  # 30-day retention
+    [[ "$output" == *"-delete"* ]]
 }
 
 @test "clean_deep_system cleans diagnostic trace logs" {
@@ -590,12 +620,29 @@ CALL_LOG="$HOME/diag_calls.log"
 source "$PROJECT_ROOT/lib/core/common.sh"
 source "$PROJECT_ROOT/lib/clean/system.sh"
 
-sudo() { return 0; }
+sudo() {
+    if [[ "$1" == "test" ]]; then
+        return 0
+    fi
+    if [[ "$1" == "find" ]]; then
+        echo "sudo_find:$*" >> "$CALL_LOG"
+        if [[ "$2" == "/private/var/db/diagnostics" ]]; then
+            printf '%s\0' \
+                "/private/var/db/diagnostics/Persist/test.tracev3" \
+                "/private/var/db/diagnostics/Special/test.tracev3"
+        fi
+        return 0
+    fi
+    return 0
+}
 safe_sudo_find_delete() {
     echo "safe_sudo_find_delete:$1:$2" >> "$CALL_LOG"
     return 0
 }
-safe_sudo_remove() { return 0; }
+safe_sudo_remove() {
+    echo "safe_sudo_remove:$1" >> "$CALL_LOG"
+    return 0
+}
 log_success() { :; }
 start_section_spinner() { :; }
 stop_section_spinner() { :; }

From 41a26204fbc1edec8fc4842d78bd6045e684cb1f Mon Sep 17 00:00:00 2001
From: tw93 <tw93@qq.com>
Date: Wed, 4 Feb 2026 16:18:13 +0800
Subject: [PATCH 11/17] perf: skip redundant -name parameter when pattern is
 wildcard

Optimization:
- Skip -name "*" in safe_sudo_find_delete when pattern matches everything
- Reduces unnecessary parameter passing to find command
- Improves performance for operations that scan all files

Rationale:
- find -name "*" is redundant as it matches everything by default
- Removing it reduces command overhead without changing behavior
---
 lib/core/file_ops.sh | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/lib/core/file_ops.sh b/lib/core/file_ops.sh
index 3ad9f76..b2c3966 100644
--- a/lib/core/file_ops.sh
+++ b/lib/core/file_ops.sh
@@ -467,7 +467,12 @@ safe_sudo_find_delete() {
 
     debug_log "Finding, sudo, in $base_dir: $pattern, age: ${age_days}d, type: $type_filter"
 
-    local find_args=("-maxdepth" "5" "-name" "$pattern" "-type" "$type_filter")
+    local find_args=("-maxdepth" "5")
+    # Skip -name if pattern is "*" (matches everything anyway, but adds overhead)
+    if [[ "$pattern" != "*" ]]; then
+        find_args+=("-name" "$pattern")
+    fi
+    find_args+=("-type" "$type_filter")
     if [[ "$age_days" -gt 0 ]]; then
         find_args+=("-mtime" "+$age_days")
     fi

From 8bf3d419f5bcb232e051ec5875299031ea1fb445 Mon Sep 17 00:00:00 2001
From: tw93 <tw93@qq.com>
Date: Wed, 4 Feb 2026 16:39:02 +0800
Subject: [PATCH 12/17] fix(raycast): defer command interpolation

---
 scripts/setup-quick-launchers.sh | 36 +++++++++++++++++++-------------
 1 file changed, 21 insertions(+), 15 deletions(-)

diff --git a/scripts/setup-quick-launchers.sh b/scripts/setup-quick-launchers.sh
index 53b07f3..216a285 100755
--- a/scripts/setup-quick-launchers.sh
+++ b/scripts/setup-quick-launchers.sh
@@ -59,12 +59,18 @@ write_raycast_script() {
 # Optional parameters:
 # @raycast.icon 🐹
 
+# ──────────────────────────────────────────────────────────
+# Script execution begins below
+# ──────────────────────────────────────────────────────────
+
 set -euo pipefail
 
 echo "🐹 Running ${title}..."
 echo ""
-CMD="${raw_cmd}"
-CMD_ESCAPED="${cmd_escaped}"
+
+# Command to execute
+_MO_RAW_CMD="${raw_cmd}"
+_MO_CMD_ESCAPED="${cmd_escaped}"
 
 has_app() {
     local name="\$1"
@@ -114,7 +120,7 @@ launch_with_app() {
         Terminal)
             if command -v osascript >/dev/null 2>&1; then
                 osascript <<'APPLESCRIPT'
-set targetCommand to "${cmd_escaped}"
+set targetCommand to "\${_MO_CMD_ESCAPED}"
 tell application "Terminal"
     activate
     do script targetCommand
@@ -126,7 +132,7 @@ APPLESCRIPT
         iTerm|iTerm2)
             if command -v osascript >/dev/null 2>&1; then
                 osascript <<'APPLESCRIPT'
-set targetCommand to "${cmd_escaped}"
+set targetCommand to "\${_MO_CMD_ESCAPED}"
 tell application "iTerm2"
     activate
     try
@@ -150,52 +156,52 @@ APPLESCRIPT
             ;;
         Alacritty)
             if launcher_available "Alacritty" && command -v open >/dev/null 2>&1; then
-                open -na "Alacritty" --args -e /bin/zsh -lc "${raw_cmd}"
+                open -na "Alacritty" --args -e /bin/zsh -lc "\${_MO_RAW_CMD}"
                 return \$?
             fi
             ;;
         Kitty)
             if has_bin "kitty"; then
-                kitty --hold /bin/zsh -lc "${raw_cmd}"
+                kitty --hold /bin/zsh -lc "\${_MO_RAW_CMD}"
                 return \$?
             elif [[ -x "/Applications/kitty.app/Contents/MacOS/kitty" ]]; then
-                "/Applications/kitty.app/Contents/MacOS/kitty" --hold /bin/zsh -lc "${raw_cmd}"
+                "/Applications/kitty.app/Contents/MacOS/kitty" --hold /bin/zsh -lc "\${_MO_RAW_CMD}"
                 return \$?
             fi
             ;;
         WezTerm)
             if has_bin "wezterm"; then
-                wezterm start -- /bin/zsh -lc "${raw_cmd}"
+                wezterm start -- /bin/zsh -lc "\${_MO_RAW_CMD}"
                 return \$?
             elif [[ -x "/Applications/WezTerm.app/Contents/MacOS/wezterm" ]]; then
-                "/Applications/WezTerm.app/Contents/MacOS/wezterm" start -- /bin/zsh -lc "${raw_cmd}"
+                "/Applications/WezTerm.app/Contents/MacOS/wezterm" start -- /bin/zsh -lc "\${_MO_RAW_CMD}"
                 return \$?
             fi
             ;;
         Ghostty)
             if has_bin "ghostty"; then
-                ghostty --command "/bin/zsh" -- -lc "${raw_cmd}"
+                ghostty --command "/bin/zsh" -- -lc "\${_MO_RAW_CMD}"
                 return \$?
             elif [[ -x "/Applications/Ghostty.app/Contents/MacOS/ghostty" ]]; then
-                "/Applications/Ghostty.app/Contents/MacOS/ghostty" --command "/bin/zsh" -- -lc "${raw_cmd}"
+                "/Applications/Ghostty.app/Contents/MacOS/ghostty" --command "/bin/zsh" -- -lc "\${_MO_RAW_CMD}"
                 return \$?
             fi
             ;;
         Hyper)
             if launcher_available "Hyper" && command -v open >/dev/null 2>&1; then
-                open -na "Hyper" --args /bin/zsh -lc "${raw_cmd}"
+                open -na "Hyper" --args /bin/zsh -lc "\${_MO_RAW_CMD}"
                 return \$?
             fi
             ;;
         WindTerm)
             if launcher_available "WindTerm" && command -v open >/dev/null 2>&1; then
-                open -na "WindTerm" --args /bin/zsh -lc "${raw_cmd}"
+                open -na "WindTerm" --args /bin/zsh -lc "\${_MO_RAW_CMD}"
                 return \$?
             fi
             ;;
         Warp)
             if launcher_available "Warp" && command -v open >/dev/null 2>&1; then
-                open -na "Warp" --args /bin/zsh -lc "${raw_cmd}"
+                open -na "Warp" --args /bin/zsh -lc "\${_MO_RAW_CMD}"
                 return \$?
             fi
             ;;
@@ -223,7 +229,7 @@ fi
 
 echo "TERM environment variable not set and no launcher succeeded."
 echo "Run this manually:"
-echo "    ${raw_cmd}"
+echo "    \${_MO_RAW_CMD}"
 exit 1
 EOF
     chmod +x "$target"

From 5edddb616b39e30a436084d2b1807c1cdc40bfae Mon Sep 17 00:00:00 2001
From: tw93 <tw93@qq.com>
Date: Wed, 4 Feb 2026 16:43:07 +0800
Subject: [PATCH 13/17] chore(raycast): clarify settings open fallback

---
 scripts/setup-quick-launchers.sh | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/scripts/setup-quick-launchers.sh b/scripts/setup-quick-launchers.sh
index 216a285..9c996b7 100755
--- a/scripts/setup-quick-launchers.sh
+++ b/scripts/setup-quick-launchers.sh
@@ -251,10 +251,10 @@ create_raycast_commands() {
 
     log_header "Raycast Configuration"
     if command -v open > /dev/null 2>&1; then
-        if open "raycast://extensions/raycast/raycast-settings/extensions" > /dev/null 2>&1; then
+        if open "raycast://extensions/raycast/raycast-settings/extensions" > /dev/null 2>&1 2> /dev/null; then
             log_step "Raycast settings opened."
         else
-            log_warn "Could not auto-open Raycast."
+            log_warn "Could not auto-open Raycast settings (raycast:// URL may be unavailable). Please open Raycast manually."
         fi
     else
         log_warn "open command not available; please open Raycast manually."
@@ -266,10 +266,10 @@ create_raycast_commands() {
     if is_interactive; then
         log_header "Finalizing Setup"
         prompt_enter "Press [Enter] to reload script directories in Raycast..."
-        if command -v open > /dev/null 2>&1 && open "raycast://extensions/raycast/raycast/reload-script-directories" > /dev/null 2>&1; then
+        if command -v open > /dev/null 2>&1 && open "raycast://extensions/raycast/raycast/reload-script-directories" > /dev/null 2>&1 2> /dev/null; then
             log_step "Raycast script directories reloaded."
         else
-            log_warn "Could not auto-reload Raycast script directories."
+            log_warn "Could not auto-reload Raycast script directories (raycast:// URL may be unavailable)."
         fi
 
         log_success "Raycast setup complete!"

From 9a6427408ede401148e65fbff682f6150a5e4ec9 Mon Sep 17 00:00:00 2001
From: tw93 <tw93@qq.com>
Date: Wed, 4 Feb 2026 16:48:15 +0800
Subject: [PATCH 14/17] chore(raycast): make setup manual

---
 scripts/setup-quick-launchers.sh | 19 ++-----------------
 1 file changed, 2 insertions(+), 17 deletions(-)

diff --git a/scripts/setup-quick-launchers.sh b/scripts/setup-quick-launchers.sh
index 9c996b7..c60369e 100755
--- a/scripts/setup-quick-launchers.sh
+++ b/scripts/setup-quick-launchers.sh
@@ -250,28 +250,13 @@ create_raycast_commands() {
     log_success "Scripts ready in: $dir"
 
     log_header "Raycast Configuration"
-    if command -v open > /dev/null 2>&1; then
-        if open "raycast://extensions/raycast/raycast-settings/extensions" > /dev/null 2>&1 2> /dev/null; then
-            log_step "Raycast settings opened."
-        else
-            log_warn "Could not auto-open Raycast settings (raycast:// URL may be unavailable). Please open Raycast manually."
-        fi
-    else
-        log_warn "open command not available; please open Raycast manually."
-    fi
-
+    log_step "Open Raycast → Settings → Extensions → Script Commands."
     echo "If Raycast asks to add a Script Directory, use:"
     echo "  $dir"
 
     if is_interactive; then
         log_header "Finalizing Setup"
-        prompt_enter "Press [Enter] to reload script directories in Raycast..."
-        if command -v open > /dev/null 2>&1 && open "raycast://extensions/raycast/raycast/reload-script-directories" > /dev/null 2>&1 2> /dev/null; then
-            log_step "Raycast script directories reloaded."
-        else
-            log_warn "Could not auto-reload Raycast script directories (raycast:// URL may be unavailable)."
-        fi
-
+        prompt_enter "Press [Enter] after clicking 'Reload Script Directories' in Raycast..."
         log_success "Raycast setup complete!"
     else
         log_warn "Non-interactive mode; skip Raycast reload. Please run 'Reload Script Directories' in Raycast."

From ba1a21f8e78bca71262e0efb875f7839b25b8a6c Mon Sep 17 00:00:00 2001
From: tw93 <tw93@qq.com>
Date: Wed, 4 Feb 2026 16:54:59 +0800
Subject: [PATCH 15/17] chore(raycast): add explicit script dir steps

---
 scripts/setup-quick-launchers.sh | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/scripts/setup-quick-launchers.sh b/scripts/setup-quick-launchers.sh
index c60369e..3de598e 100755
--- a/scripts/setup-quick-launchers.sh
+++ b/scripts/setup-quick-launchers.sh
@@ -251,12 +251,13 @@ create_raycast_commands() {
 
     log_header "Raycast Configuration"
     log_step "Open Raycast → Settings → Extensions → Script Commands."
-    echo "If Raycast asks to add a Script Directory, use:"
-    echo "  $dir"
+    echo "1. Click \"+\" → Add Script Directory."
+    echo "2. Choose: $dir"
+    echo "3. Click \"Reload Script Directories\"."
 
     if is_interactive; then
         log_header "Finalizing Setup"
-        prompt_enter "Press [Enter] after clicking 'Reload Script Directories' in Raycast..."
+        prompt_enter "Press [Enter] after finishing the steps above in Raycast..."
         log_success "Raycast setup complete!"
     else
         log_warn "Non-interactive mode; skip Raycast reload. Please run 'Reload Script Directories' in Raycast."

From 8861fe6b5f2cce059cad8ec81deae82b68ef0994 Mon Sep 17 00:00:00 2001
From: tw93 <tw93@qq.com>
Date: Wed, 4 Feb 2026 16:58:39 +0800
Subject: [PATCH 16/17] chore(raycast): prompt before continuing

---
 scripts/setup-quick-launchers.sh | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/scripts/setup-quick-launchers.sh b/scripts/setup-quick-launchers.sh
index 3de598e..e72080d 100755
--- a/scripts/setup-quick-launchers.sh
+++ b/scripts/setup-quick-launchers.sh
@@ -257,7 +257,8 @@ create_raycast_commands() {
 
     if is_interactive; then
         log_header "Finalizing Setup"
-        prompt_enter "Press [Enter] after finishing the steps above in Raycast..."
+        log_warn "Please complete the Raycast steps above before continuing."
+        prompt_enter "Press [Enter] to continue..."
         log_success "Raycast setup complete!"
     else
         log_warn "Non-interactive mode; skip Raycast reload. Please run 'Reload Script Directories' in Raycast."

From cb19899eaab28d794d33f0d0554c9525e422d0fc Mon Sep 17 00:00:00 2001
From: tw93 <tw93@qq.com>
Date: Wed, 4 Feb 2026 17:34:04 +0800
Subject: [PATCH 17/17] fix(apps): correct array initialization for matches in
 clean_orphaned_app_data

---
 lib/clean/apps.sh | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/lib/clean/apps.sh b/lib/clean/apps.sh
index adedcae..11d064c 100644
--- a/lib/clean/apps.sh
+++ b/lib/clean/apps.sh
@@ -291,7 +291,9 @@ clean_orphaned_app_data() {
                 local iteration_count=0
                 local old_ifs=$IFS
                 IFS=$'\n'
-                local -a matches=($item_path)
+                local -a matches=()
+                # shellcheck disable=SC2206
+                matches=($item_path)
                 IFS=$old_ifs
                 if [[ ${#matches[@]} -eq 0 ]]; then
                     continue