Support debug

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,50 @@
+---
+name: Bug Report
+about: Report a bug or issue with Mole
+title: '[BUG] '
+labels: bug
+assignees: ''
+---
+
+## Describe the bug
+
+A clear and concise description of what the bug is.
+
+## Steps to reproduce
+
+1. Run command: `mo ...`
+2. ...
+3. See error
+
+## Expected behavior
+
+A clear and concise description of what you expected to happen.
+
+## Debug logs
+
+Please run the command with `--debug` flag and paste the output here:
+
+```bash
+mo <command> --debug
+# Example: mo clean --debug or mo clean --dry-run --debug
+```
+
+<details>
+<summary>Debug output</summary>
+
+```text
+Paste the debug output here
+```
+
+</details>
+
+## Environment
+
+- Mole version: (run `mo --version`)
+- macOS version: (run `sw_vers`)
+- Installation method: (Homebrew / curl script)
+- Architecture: (Intel / Apple Silicon)
+
+## Additional context
+
+Add any other context about the problem here, such as screenshots or related issues.

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Telegram Community
+    url: https://t.me/+GclQS9ZnxyI2ODQ1
+    about: Join our Telegram group for questions and discussions
+  - name: GitHub Discussions
+    url: https://github.com/tw93/mole/discussions
+    about: Ask questions and share ideas with the community

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,27 @@
+---
+name: Feature Request
+about: Suggest an idea for Mole
+title: '[FEATURE] '
+labels: enhancement
+assignees: ''
+---
+
+## Feature description
+
+A clear and concise description of the feature you'd like to see.
+
+## Use case
+
+Describe the problem this feature would solve or the benefit it would provide.
+
+## Proposed solution
+
+How do you envision this feature working?
+
+## Alternatives considered
+
+Have you considered any alternative solutions or workarounds?
+
+## Additional context
+
+Add any other context, mockups, or examples about the feature request here.

README.md

@@ -65,6 +65,7 @@ mo --version            # Show installed version
 - Use `mo clean --whitelist` to manage protected caches.
 - Use `mo touchid` to approve sudo with Touch ID instead of typing your password.
 - Prefer Vim-style navigation? All menus understand `h/j/k/l` in addition to the arrow keys.
+- Run into issues? Enable debug mode with `--debug` flag for detailed logs: `mo clean --debug` or `mo clean --dry-run --debug`.
 
 ## Features in Detail
 
@@ -193,6 +194,7 @@ For Raycast, reload by running `Reload Script Directories` or restarting Raycast
 
 - If Mole freed storage for you, consider starring the repo or sharing it with friends needing a cleaner Mac.
 - Have ideas or fixes? Open an issue or PR and help shape Mole's future together with the community.
+- Report bugs with debug logs by running `mo clean --debug` or `mo <command> --debug` and sharing the output in your issue.
 - Love cats? Treat Tangyuan and Cola to canned food via <a href="https://miaoyan.app/cats.html?name=Mole" target="_blank">this link</a> and keep the mascots purring.
 
 ## License

bin/clean.sh

@@ -177,6 +177,7 @@ start_section() {
     TRACK_SECTION=1
     SECTION_ACTIVITY=0
     CURRENT_SECTION="$1"
+    debug_log "Starting section: $1"
     echo ""
     echo -e "${PURPLE_BOLD}${ICON_ARROW} $1${NC}"
 
@@ -212,6 +213,8 @@ safe_clean() {
         targets=("${@:1:$#-1}")
     fi
 
+    debug_log "safe_clean: description='$description', target_count=${#targets[@]}"
+
     local removed_any=0
     local total_size_bytes=0
     local total_count=0
@@ -461,6 +464,9 @@ start_cleanup() {
     echo -e "${PURPLE_BOLD}Clean Your Mac${NC}"
     echo ""
 
+    debug_log "Starting cleanup process"
+    debug_log "DRY_RUN=$DRY_RUN, SYSTEM_CLEAN=$SYSTEM_CLEAN"
+
     if [[ "$DRY_RUN" != "true" && -t 0 ]]; then
         echo -e "${YELLOW}☻${NC} First time? Run ${GRAY}mo clean --dry-run${NC} first to preview changes"
     fi
@@ -469,6 +475,7 @@ start_cleanup() {
         echo -e "${YELLOW}Dry Run Mode${NC} - Preview only, no deletions"
         echo ""
         SYSTEM_CLEAN=false
+        debug_log "Dry run mode enabled"
 
         # Initialize export list file
         mkdir -p "$(dirname "$EXPORT_LIST_FILE")"
@@ -536,6 +543,13 @@ EOF
 perform_cleanup() {
     echo -e "${BLUE}${ICON_ADMIN}${NC} $(detect_architecture) | Free space: $(get_free_space)"
 
+    debug_log "Whitelist patterns loaded: ${#WHITELIST_PATTERNS[@]}"
+    if [[ "${MO_DEBUG:-}" == "1" && ${#WHITELIST_PATTERNS[@]} -gt 0 ]]; then
+        for pattern in "${WHITELIST_PATTERNS[@]}"; do
+            debug_log "  Whitelist: $pattern"
+        done
+    fi
+
     # Pre-check TCC permissions upfront (delegated to clean_caches module)
     check_tcc_permissions
 

bin/optimize.sh

@@ -385,8 +385,8 @@ main() {
         log_error "Invalid system health data format"
         echo -e "${YELLOW}Tip:${NC} Check if jq, awk, sysctl, and df commands are available"
         if [[ "${MO_DEBUG:-}" == "1" ]]; then
-            echo "DEBUG: Generated JSON:"
+            debug_log "Generated JSON:"
-            echo "$health_json"
+            debug_log "$health_json"
         fi
         exit 1
     fi
@@ -398,17 +398,13 @@ main() {
     # Show system health
     show_system_health "$health_json"
 
-    if [[ "${MO_DEBUG:-}" == "1" ]]; then
+    debug_log "System health displayed"
-        echo "DEBUG: System health displayed"
-    fi
 
     # Parse and display optimizations
     local -a safe_items=()
     local -a confirm_items=()
 
-    if [[ "${MO_DEBUG:-}" == "1" ]]; then
+    debug_log "Parsing optimizations..."
-        echo "DEBUG: Parsing optimizations..."
-    fi
 
     # Use temp file instead of process substitution to avoid hanging
     local opts_file
@@ -417,7 +413,7 @@ main() {
 
     if [[ "${MO_DEBUG:-}" == "1" ]]; then
         local opt_count=$(wc -l < "$opts_file" | tr -d ' ')
-        echo "DEBUG: Found $opt_count optimizations"
+        debug_log "Found $opt_count optimizations"
     fi
 
     while IFS= read -r opt_json; do
@@ -438,23 +434,16 @@ main() {
         fi
     done < "$opts_file"
 
-    if [[ "${MO_DEBUG:-}" == "1" ]]; then
+    debug_log "Parsing complete. Safe: ${#safe_items[@]}, Confirm: ${#confirm_items[@]}"
-        echo "DEBUG: Parsing complete. Safe: ${#safe_items[@]}, Confirm: ${#confirm_items[@]}"
-    fi
 
     # Execute all optimizations
     local first_heading=true
 
-    # Debug: show what we're about to do
+    debug_log "About to request sudo. Safe items: ${#safe_items[@]}, Confirm items: ${#confirm_items[@]}"
-    if [[ "${MO_DEBUG:-}" == "1" ]]; then
-        echo "DEBUG: About to request sudo. Safe items: ${#safe_items[@]}, Confirm items: ${#confirm_items[@]}"
-    fi
 
     ensure_sudo_session "System optimization requires admin access" || true
 
-    if [[ "${MO_DEBUG:-}" == "1" ]]; then
+    debug_log "Sudo session established or skipped"
-        echo "DEBUG: Sudo session established or skipped"
-    fi
 
     # Run safe optimizations
     if [[ ${#safe_items[@]} -gt 0 ]]; then

bin/uninstall.sh

@@ -69,6 +69,7 @@ format_last_used_summary() {
 
 # Scan applications and collect information
 scan_applications() {
+    debug_log "scan_applications: Starting application scan"
     # Simplified cache: only check timestamp (24h TTL)
     local cache_dir="$HOME/.cache/mole"
     local cache_file="$cache_dir/app_scan_cache"
@@ -82,9 +83,13 @@ scan_applications() {
         [[ $cache_age -eq $(date +%s) ]] && cache_age=86401 # Handle missing file
         if [[ $cache_age -lt $cache_ttl ]]; then
             # Cache hit - return immediately
+            debug_log "scan_applications: Using cached app list (age: ${cache_age}s)"
             echo "$cache_file"
             return 0
         fi
+        debug_log "scan_applications: Cache expired (age: ${cache_age}s > ${cache_ttl}s)"
+    else
+        debug_log "scan_applications: No cache found, performing fresh scan"
     fi
 
     # Cache miss - show scanning feedback below

lib/clean/user.sh

@@ -99,6 +99,7 @@ clean_sandboxed_app_caches() {
 
 # Clean browser caches (Safari, Chrome, Edge, Firefox, etc.)
 clean_browsers() {
+    debug_log "clean_browsers: Starting browser cache cleanup"
     safe_clean ~/Library/Caches/com.apple.Safari/* "Safari cache"
 
     # Chrome/Chromium
@@ -121,12 +122,16 @@ clean_browsers() {
 
     # Service Worker CacheStorage (all profiles)
     # Show loading indicator for potentially slow scan
+    debug_log "clean_browsers: Scanning for Service Worker caches"
     if [[ -t 1 ]]; then
         MOLE_SPINNER_PREFIX="  " start_inline_spinner "Scanning browser Service Worker caches..."
     fi
 
-    # Scan for Service Worker caches with timeout protection
+    # Scan for Service Worker caches
+    # Use process substitution to avoid subshell issues with set -e
+    local sw_count=0
     while IFS= read -r sw_path; do
+        ((sw_count++))
         [[ -z "$sw_path" ]] && continue
         local profile_name=$(basename "$(dirname "$(dirname "$sw_path")")")
         local browser_name="Chrome"
@@ -135,7 +140,7 @@ clean_browsers() {
         [[ "$sw_path" == *"Arc"* ]] && browser_name="Arc"
         [[ "$profile_name" != "Default" ]] && browser_name="$browser_name ($profile_name)"
         clean_service_worker_cache "$browser_name" "$sw_path"
-    done < <(run_with_timeout 10 find "$HOME/Library/Application Support/Google/Chrome" \
+    done < <(find "$HOME/Library/Application Support/Google/Chrome" \
         "$HOME/Library/Application Support/Microsoft Edge" \
         "$HOME/Library/Application Support/BraveSoftware/Brave-Browser" \
         "$HOME/Library/Application Support/Arc/User Data" \
@@ -145,6 +150,7 @@ clean_browsers() {
     if [[ -t 1 ]]; then
         stop_inline_spinner
     fi
+    debug_log "clean_browsers: Found $sw_count Service Worker cache paths"
 }
 
 # Clean cloud storage app caches

lib/core/common.sh

@@ -328,6 +328,13 @@ log_error() {
     echo "[$(date '+%Y-%m-%d %H:%M:%S')] ERROR: $1" >> "$LOG_FILE" 2> /dev/null || true
 }
 
+# Debug logging - only shown when MO_DEBUG=1
+debug_log() {
+    if [[ "${MO_DEBUG:-}" == "1" ]]; then
+        echo -e "${GRAY}[DEBUG]${NC} $*" >&2
+    fi
+}
+
 # Run command with optional error handling
 # Usage: run_silent command args...  # Ignore errors
 #        run_logged command args...  # Log errors but continue

lib/uninstall/batch.sh

@@ -48,6 +48,7 @@ decode_file_list() {
 # Args: $1 = bundle_id, $2 = has_system_files (true/false)
 stop_launch_services() {
     local bundle_id="$1"
+    debug_log "stop_launch_services: Stopping services for $bundle_id"
     local has_system_files="${2:-false}"
 
     # User-level Launch Agents

mole

@@ -22,7 +22,7 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$SCRIPT_DIR/lib/core/common.sh"
 
 # Version info
-VERSION="1.11.24"
+VERSION="1.11.25"
 MOLE_TAGLINE="can dig deep to clean your Mac."
 
 # Check if Touch ID is already configured
@@ -174,6 +174,9 @@ show_help() {
     printf "  %s%-28s%s %s\n" "$GREEN" "mo --version" "$NC" "Show version"
     printf "  %s%-28s%s %s\n" "$GREEN" "mo --help" "$NC" "Show help"
     echo
+    printf "%s%s%s\n" "$BLUE" "OPTIONS" "$NC"
+    printf "  %s%-28s%s %s\n" "$GREEN" "--debug" "$NC" "Show detailed debug logs"
+    echo
 }
 
 # Simple update function
@@ -672,24 +675,42 @@ interactive_main_menu() {
 }
 
 main() {
-    case "${1:-""}" in
+    # Parse global flags from any position in arguments
+    local -a args=()
+    for arg in "$@"; do
+        case "$arg" in
+            --debug)
+                export MO_DEBUG=1
+                ;;
+            *)
+                args+=("$arg")
+                ;;
+        esac
+    done
+
+    # Show debug indicator if enabled
+    if [[ "${MO_DEBUG:-}" == "1" && -t 2 ]]; then
+        echo -e "${GRAY}[DEBUG MODE ENABLED]${NC}" >&2
+    fi
+
+    case "${args[0]:-""}" in
         "optimize")
-            exec "$SCRIPT_DIR/bin/optimize.sh"
+            exec "$SCRIPT_DIR/bin/optimize.sh" "${args[@]:1}"
             ;;
         "clean")
-            exec "$SCRIPT_DIR/bin/clean.sh" "${@:2}"
+            exec "$SCRIPT_DIR/bin/clean.sh" "${args[@]:1}"
             ;;
         "uninstall")
-            exec "$SCRIPT_DIR/bin/uninstall.sh"
+            exec "$SCRIPT_DIR/bin/uninstall.sh" "${args[@]:1}"
             ;;
         "analyze")
-            exec "$SCRIPT_DIR/bin/analyze.sh" "${@:2}"
+            exec "$SCRIPT_DIR/bin/analyze.sh" "${args[@]:1}"
             ;;
         "status")
-            exec "$SCRIPT_DIR/bin/status.sh" "${@:2}"
+            exec "$SCRIPT_DIR/bin/status.sh" "${args[@]:1}"
             ;;
         "touchid")
-            exec "$SCRIPT_DIR/bin/touchid.sh" "${@:2}"
+            exec "$SCRIPT_DIR/bin/touchid.sh" "${args[@]:1}"
             ;;
         "update")
             update_mole
@@ -711,7 +732,7 @@ main() {
             interactive_main_menu
             ;;
         *)
-            echo "Unknown command: $1"
+            echo "Unknown command: ${args[0]}"
             echo "Use 'mole --help' for usage information."
             exit 1
             ;;