Enhance error handling and user interruption responses across multiple scripts

src/backup_imap_emails.py

@@ -885,11 +885,17 @@ def main():
             print("Use this file when restoring to reapply read/starred status to emails.")
 
     except KeyboardInterrupt:
-        print("\nBackup interrupted by user.")
-        sys.exit(0)
-    except Exception as e:
-        print(f"Fatal Error: {e}")
+        raise
+    # Let exceptions propagate to the main entry point handler
+    # so we get the correct exit code (1)
 
 
 if __name__ == "__main__":
-    main()
+    try:
+        main()
+    except KeyboardInterrupt:
+        print("\nProcess terminated by user.")
+        sys.exit(0)
+    except Exception as e:
+        print(f"Fatal Error: {e}")
+        sys.exit(1)

src/compare_imap_folders.py

@@ -59,6 +59,7 @@ Examples:
 
 import argparse
 import os
+import sys
 
 import imap_common
 import imap_oauth2
@@ -304,26 +305,35 @@ def main():
         print("-" * len(header))
         print(f"{'TOTAL':<40} | {total_src:>10} | {total_dest:>10} | {total_src - total_dest:>10}")
 
-    except Exception as e:
-        print(f"\nFatal Error: {e}")
-        if "Too many simultaneous connections" in str(e):
-            print("Tip: Wait a few minutes for previous connections to timeout or check other active scripts.")
+    except KeyboardInterrupt:
+        # Re-raise to be handled by the outer block, but ensure finally runs
+        raise
+
+    # Let exceptions propagate to the main entry point handler
+    # so we get the correct exit code (1)
 
     finally:
         # Check source connection state and logout if possible
         if src:
             try:
                 src.logout()
-            except Exception:
+            except BaseException:
                 pass
 
         # Check dest connection state and logout if possible
         if dest:
             try:
                 dest.logout()
-            except Exception:
+            except BaseException:
                 pass
 
 
 if __name__ == "__main__":
-    main()
+    try:
+        main()
+    except KeyboardInterrupt:
+        print("\nProcess terminated by user.")
+        sys.exit(0)
+    except Exception as e:
+        print(f"Fatal Error: {e}")
+        sys.exit(1)

src/count_imap_emails.py

@@ -236,4 +236,11 @@ def main(argv: Optional[list[str]] = None) -> None:
 
 
 if __name__ == "__main__":
-    main()
+    try:
+        main()
+    except KeyboardInterrupt:
+        print("\nProcess terminated by user.")
+        sys.exit(0)
+    except Exception as e:
+        print(f"Fatal Error: {e}")
+        sys.exit(1)

src/migrate_imap_emails.py

@@ -1102,12 +1102,18 @@ def main():
         src_main.logout()
         dest_main.logout()
 
+    except KeyboardInterrupt:
+        raise
+    # Let exceptions propagate to the main entry point handler
+    # so we get the correct exit code (1)
+
+
+if __name__ == "__main__":
+    try:
+        main()
     except KeyboardInterrupt:
         safe_print("\n\nProcess terminated by user.")
         sys.exit(0)
     except Exception as e:
         safe_print(f"Fatal Error: {e}")
-
-
-if __name__ == "__main__":
-    main()
+        sys.exit(1)

src/restore_imap_emails.py

@@ -959,7 +959,16 @@ def main():
         print("\nRestore completed successfully.")
 
     except KeyboardInterrupt:
-        print("\nRestore interrupted by user.")
+        raise
+    # Let exceptions propagate to the main entry point handler
+    # so we get the correct exit code (1)
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except KeyboardInterrupt:
+        print("\nProcess terminated by user.")
         sys.exit(0)
     except Exception as e:
         print(f"Fatal Error: {e}")
@@ -967,7 +976,3 @@ def main():
 
         traceback.print_exc()
         sys.exit(1)
-
-
-if __name__ == "__main__":
-    main()