@codebend3r/che 1.1.0 → 1.2.0

package/bin/drives/ping-nas.py

@@ -1,7 +1,10 @@
 #!/usr/bin/env python3
 """📡 Keep-alive pinger for the NAS drives.
 
-Each cycle pings every host and verifies it is still mounted under /Volumes.
+Each cycle probes every host's SMB port and verifies it is still mounted under
+/Volumes. The probe is a TCP connect to port 445 rather than ICMP, because the
+Synology firewalls drop ICMP echo while still serving SMB.
+
 If a drive is reachable but the share has dropped off /Volumes (eject, network
 blip, sleep) it is silently remounted via AppleScript's ``mount volume`` using
 Keychain credentials, with no Finder modals.
@@ -23,108 +26,93 @@ Options:
 
 from __future__ import annotations
 
-import os
-import re
 import signal
 import sys
 import time
 from pathlib import Path
-from types import FrameType
 
 sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
 
+from nas import SMB_USER, NasDrive, is_mounted, mount_smb, select_drives, smb_url
 from utils import (
     add_bool_flag,
     build_parser,
+    heading,
     info,
     log,
-    note,
+    parse_count,
     run,
     run_cli,
     success,
     warning,
 )
 
-__version__ = "3.3.0"
-
-SMB_USER = "crivas"
-
-DRIVES: tuple[tuple[str, str], ...] = (
-    ("Meleys", "192.168.50.2"),
-    ("Vermithor", "192.168.50.3"),
-    ("Caraxes", "192.168.50.4"),
-    ("Syrax", "192.168.50.5"),
-    ("Vhagar", "192.168.50.6"),
-)
-
-_cycle = 0
+__version__ = "3.4.0"
 
+SMB_PORT = 445
 
-def is_mounted(name: str) -> bool:
-    """True when something is actually mounted at ``/Volumes/<name>``."""
-    return os.path.ismount(f"/Volumes/{name}")
 
+def smb_reachable(ip: str, timeout: int) -> bool:
+    """One TCP connect to the SMB port with a per-host timeout in seconds.
 
-def ping_host(ip: str, timeout: int) -> bool:
-    """One ICMP probe with a per-host timeout. macOS ``ping -t`` is seconds."""
-    completed = run(["ping", "-c", "1", "-t", str(timeout), ip], check=False, capture=True)
+    ICMP is useless here: the NAS firewalls drop echo requests, so ``ping``
+    reported every drive unreachable while the shares were mounted fine. The
+    probe goes through Apple's ``/usr/bin/nc`` rather than a Python socket
+    because macOS Local Network privacy can deny LAN connections from a
+    Homebrew Python (``EHOSTUNREACH``) while exempting system binaries.
+    """
+    completed = run(
+        ["/usr/bin/nc", "-z", "-G", str(timeout), ip, str(SMB_PORT)],
+        check=False,
+        capture=True,
+    )
     return completed.returncode == 0
 
 
 def remount_drive(name: str, host: str) -> bool:
     """Remount one drive via AppleScript. True on success."""
-    url = f"smb://{SMB_USER}@{host}/{name}"
-    log(f"  🔗 Remounting {name} ({url})...")
-
-    completed = run(["osascript", "-e", f'mount volume "{url}"'], check=False, capture=True)
-    if completed.returncode == 0:
-        success(f"  ✅ {name} remounted 🐉")
-        return True
+    log(f"  🔗 Remounting {name} ({smb_url(name, host)})...")
+    if not mount_smb(name, host):
+        return False
 
-    warning(f"  ❌ mount failed for {url}")
-    stderr = (completed.stderr or "").strip()
-    if stderr:
-        warning(f"     {stderr}")
-    warning(f"     Check that Keychain has a password for '{SMB_USER}@{host}'.")
-    return False
+    success(f"  ✅ {name} remounted 🐉")
+    return True
 
 
 def ping_all_nas(
-    active: list[tuple[str, str]],
+    active: list[NasDrive],
     *,
+    cycle: int,
     ping_timeout: int,
     remount: bool,
     use_ip: bool,
     quiet: bool,
 ) -> None:
-    """Run one full check cycle over the active drive list."""
-    global _cycle
-    _cycle += 1
-
+    """Run check cycle number ``cycle`` over the active drive list."""
     unreachable = 0
     unmounted = 0
     remounted = 0
     remount_failed = 0
 
     if not quiet:
-        log(f"🔄 Cycle #{_cycle} — checking {len(active)} NAS drive(s)...")
+        log(f"🔄 Cycle #{cycle} — checking {len(active)} NAS drive(s)...")
 
-    for name, ip in active:
-        if not ping_host(ip, ping_timeout):
-            warning(f"  ❌ {name} ({ip}) — ping failed")
+    for drive in active:
+        if not smb_reachable(drive.ip, ping_timeout):
+            warning(f"  ❌ {drive.name} ({drive.ip}): SMB port {SMB_PORT} unreachable")
             unreachable += 1
             continue
 
-        if is_mounted(name):
+        if is_mounted(drive.name):
             if not quiet:
-                log(f"  ✅ 🐉 {name} ({ip}) — mounted")
+                log(f"  ✅ 🐉 {drive.name} ({drive.ip}) — mounted")
             continue
 
-        warning(f"  ⚠️  {name} ({ip}) — reachable but not mounted")
+        warning(f"  ⚠️  {drive.name} ({drive.ip}) — reachable but not mounted")
         unmounted += 1
 
         if remount:
-            if remount_drive(name, ip if use_ip else name):
+            if remount_drive(drive.name, drive.host(use_ip=use_ip)):
                 remounted += 1
             else:
                 remount_failed += 1
@@ -146,32 +134,23 @@ def ping_all_nas(
     warning(f"⚠️  Cycle summary: {' '.join(parts)}")
 
 
-def _shutdown(signum: int, frame: FrameType | None) -> None:
-    """Exit 0 on Ctrl-C, matching the shell version's INT/TERM trap."""
-    print()
-    info(f"👋 Stopping keep-alive pinger after {_cycle} cycle(s).")
-    sys.exit(0)
-
-
 def main(argv: list[str] | None = None) -> int:
     parser = build_parser(
         prog="ping-nas",
         description="📡 Keep-alive pinger for the NAS drives.",
         epilog=(
-            "Each cycle pings every host and verifies it is still mounted under\n"
-            "/Volumes. A drive that is reachable but has dropped off /Volumes is\n"
-            f"silently remounted via AppleScript as '{SMB_USER}' using Keychain\n"
-            "credentials, with no Finder modals."
+            f"Each cycle probes every host's SMB port ({SMB_PORT}) and verifies it is\n"
+            "still mounted under /Volumes. A drive that is reachable but has\n"
+            "dropped off /Volumes is silently remounted via AppleScript as\n"
+            f"'{SMB_USER}' using Keychain credentials, with no Finder modals."
         ),
     )
-    # --interval and --ping-timeout stay strings so the shell version's own
-    # message survives; `type=int` would let argparse own the failure first.
+    # Strings, validated by parse_count below rather than `type=int`.
     parser.add_argument(
         "--interval", default="300", metavar="N", help="Seconds between cycles (default: 300)"
     )
     parser.add_argument(
         "--ping-timeout",
-        dest="ping_timeout",
         default="2",
         metavar="N",
         help="Per-host ping timeout in seconds (default: 2)",
@@ -182,61 +161,54 @@ def main(argv: list[str] | None = None) -> int:
     add_bool_flag(
         parser,
         "--no-remount",
-        dest="no_remount",
         allow_value=False,
         help="Detect-only: warn about missing mounts, don't remount",
     )
-    add_bool_flag(
-        parser,
-        "--use-ip",
-        dest="use_ip",
-        help="Remount via //USER@IP/NAME instead of //USER@NAME/NAME",
-    )
+    add_bool_flag(parser, "--use-ip", help="Remount via //USER@IP/NAME instead of //USER@NAME/NAME")
     add_bool_flag(parser, "--once", help="Run a single cycle and exit (useful from cron)")
     add_bool_flag(parser, "--quiet", help="Only log failures, remount attempts, and cycle summary")
     args = parser.parse_args(argv)
 
-    values: dict[str, int] = {}
-    for flag, raw in (("--interval", args.interval), ("--ping-timeout", args.ping_timeout)):
-        if not re.fullmatch(r"[0-9]+", raw) or int(raw) < 1:
-            warning(f"❌ {flag} must be a positive integer (got: {raw})")
-            return 1
-        values[flag] = int(raw)
-    interval = values["--interval"]
-    ping_timeout = values["--ping-timeout"]
+    interval = parse_count(args.interval, "--interval", minimum=1)
+    ping_timeout = parse_count(args.ping_timeout, "--ping-timeout", minimum=1)
 
-    active = [(n, ip) for n, ip in DRIVES if not args.only or n.lower() == args.only.lower()]
+    active = select_drives(args.only)
     if not active:
         warning(f"❌ No drives matched --only={args.only}")
         return 1
 
-    signal.signal(signal.SIGINT, _shutdown)
-    signal.signal(signal.SIGTERM, _shutdown)
-
-    note("═══════════════════════════════════════════")
-    note("📡  ping-nas")
-    note("═══════════════════════════════════════════")
-
-    cycle_kwargs = {
-        "ping_timeout": ping_timeout,
-        "remount": not args.no_remount,
-        "use_ip": args.use_ip,
-        "quiet": args.quiet,
-    }
-
-    if args.once:
-        ping_all_nas(active, **cycle_kwargs)
+    # INT and TERM both stop the pinger with exit 0, matching the shell
+    # version's trap. SIGINT is set too, not left to Python's default, because
+    # a pinger started in the background by a script inherits it ignored.
+    for signum in (signal.SIGINT, signal.SIGTERM):
+        signal.signal(signum, signal.default_int_handler)
+    cycle = 0
+    try:
+        heading("📡  ping-nas")
+        if not args.once:
+            info(
+                f"🚀 Keep-alive pinger started for {len(active)} NAS "
+                f"(every {interval}s). Press Ctrl-C to stop."
+            )
+
+        while True:
+            cycle += 1
+            ping_all_nas(
+                active,
+                cycle=cycle,
+                ping_timeout=ping_timeout,
+                remount=not args.no_remount,
+                use_ip=args.use_ip,
+                quiet=args.quiet,
+            )
+            if args.once:
+                return 0
+            time.sleep(interval)
+    except KeyboardInterrupt:
+        print()
+        info(f"👋 Stopping keep-alive pinger after {cycle} cycle(s).")
         return 0
 
-    info(
-        f"🚀 Keep-alive pinger started for {len(active)} NAS "
-        f"(every {interval}s). Press Ctrl-C to stop."
-    )
-
-    while True:
-        ping_all_nas(active, **cycle_kwargs)
-        time.sleep(interval)
-
 
 if __name__ == "__main__":
     run_cli(main)

package/bin/files/compress-folders.py

@@ -25,6 +25,9 @@ sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
 from utils import (
     add_bool_flag,
     build_parser,
+    dry_run_complete,
+    footer_rule,
+    heading,
     info,
     log,
     note,
@@ -67,10 +70,7 @@ def _walk_entries(folder: Path) -> list[tuple[Path, str]]:
         dirnames.sort()
         filenames.sort()
 
-        for name in dirnames:
-            child = directory / name
-            entries.append((child, str(child.relative_to(parent))))
-        for name in filenames:
+        for name in (*dirnames, *filenames):
             child = directory / name
             entries.append((child, str(child.relative_to(parent))))
 
@@ -130,10 +130,7 @@ def main(argv: list[str] | None = None) -> int:
 
     root = scan_root(args.path)
 
-    header_suffix = " 🌵 (dry run)" if args.dry_run else ""
-    note("═══════════════════════════════════════════")
-    note(f"📦  compress-folders{header_suffix}")
-    note("═══════════════════════════════════════════")
+    heading("📦  compress-folders", dry_run=args.dry_run)
     note(f"Parent: {root}")
 
     compressed = 0
@@ -168,11 +165,10 @@ def main(argv: list[str] | None = None) -> int:
         success(f"  ✅ {folder.name}.zip")
         compressed += 1
 
-    print()
-    note("─────────────────────────────────────────────")
+    footer_rule()
     if args.dry_run:
         success(f"🌵 Would compress: {compressed} folder(s)")
-        log("💡 Dry run complete. Nothing was actually changed.")
+        dry_run_complete()
         return 0
 
     success(f"✅ Compressed: {compressed}")

package/bin/files/delete-by-ext.py

@@ -14,7 +14,7 @@ Options:
   --help        Show help
 
 Env:
-  DRY_RUN=false Opt out of the preview-only default (used by the .zshrc wrapper)
+  DRY_RUN=false Opt out of the preview-only default (used by the generated wrapper)
 """
 
 from __future__ import annotations
@@ -32,7 +32,8 @@ from utils import (
     iter_files,
     log,
     normalize_extensions,
-    note,
+    note_settings,
+    remove_or_warn,
     run_cli,
     scan_root,
     warning,
@@ -68,11 +69,12 @@ def main(argv: list[str] | None = None) -> int:
 
     extensions = normalize_extensions(args.ext)
 
-    note(f"Scanning: {args.path}")
-    note(f"Extensions: {' '.join(extensions)}")
-    note(f"Dry run: {str(args.dry_run).lower()}")
-    note(f"Verbose: {str(args.verbose).lower()}")
-    note("----------------------------------------------------")
+    note_settings(
+        ("Scanning", args.path),
+        ("Extensions", " ".join(extensions)),
+        ("Dry run", args.dry_run),
+        ("Verbose", args.verbose),
+    )
 
     if not extensions:
         warning("--ext is required")
@@ -91,13 +93,7 @@ def main(argv: list[str] | None = None) -> int:
             continue
 
         log(f"Deleting: {path}")
-        try:
-            path.unlink()
-        except OSError as exc:
-            # The shell version aborted the whole run here under `set -e`.
-            # Continuing and reporting at the end is more useful on a NAS
-            # where one busy file should not strand the rest of the sweep.
-            warning(f"  ✗ Failed to delete {path}: {exc}")
+        if not remove_or_warn(path):
             failures += 1
 
     log("Completed.")

package/bin/files/delete-empty-folders.py

@@ -15,13 +15,14 @@ Options:
   --help        Show help
 
 Env:
-  DRY_RUN=false Opt out of the preview-only default (used by the .zshrc wrapper)
+  DRY_RUN=false Opt out of the preview-only default (used by the generated wrapper)
 """
 
 from __future__ import annotations
 
 import os
 import sys
+from collections.abc import Container
 from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
@@ -33,12 +34,14 @@ from utils import (
     info,
     log,
     note,
+    note_settings,
+    remove_or_warn,
+    report_walk_error,
     run_cli,
     scan_root,
-    warning,
 )
 
-__version__ = "3.0.0"
+__version__ = "3.1.0"
 
 
 def directories_deepest_first(root: Path) -> list[Path]:
@@ -47,29 +50,23 @@ def directories_deepest_first(root: Path) -> list[Path]:
     This is ``find -depth -type d``. The ordering is what makes cascading work:
     emptying a leaf lets its parent become empty, and the parent is visited
     afterwards. The whole tree is enumerated up front - exactly like ``find``
-    piping into a loop - and emptiness is re-checked at visit time against the
-    live filesystem, so a directory emptied earlier in the run is seen as
-    empty when its turn comes.
+    piping into a loop - and emptiness is re-checked at visit time, so a
+    directory emptied earlier in the run is seen as empty when its turn comes.
     """
+    walk = os.walk(root, topdown=False, followlinks=False, onerror=report_walk_error)
+    return [Path(dirpath) for dirpath, _, _ in walk]
 
-    def _on_error(exc: OSError) -> None:
-        warning(f"find: {exc.filename}: {exc.strerror}")
 
-    found: list[Path] = []
-    for dirpath, _, _ in os.walk(root, topdown=False, followlinks=False, onerror=_on_error):
-        found.append(Path(dirpath))
-    return found
+def is_strictly_empty(path: Path, gone: Container[Path]) -> bool:
+    """True only when the directory has no entries at all, hidden included.
 
-
-def is_strictly_empty(path: Path) -> bool:
-    """True only when the directory has no entries at all, hidden included."""
+    Entries in ``gone`` do not count: they are the directories a dry run has
+    already reported, which a real run would have removed by now.
+    """
     try:
-        next(path.iterdir())
-    except StopIteration:
-        return True
+        return all(entry in gone for entry in path.iterdir())
     except OSError:
         return False
-    return False
 
 
 def main(argv: list[str] | None = None) -> int:
@@ -89,40 +86,39 @@ def main(argv: list[str] | None = None) -> int:
     info(f"Running command in {Path.cwd()}")
     args = parser.parse_args(argv)
 
-    if not args.path:
-        warning("Error: --path is required.")
-        return 1
-
+    # An empty --path reads "--path is required", where the shell version
+    # printed "Error: --path is required.".
     root = scan_root(args.path)
 
-    note(f"Searching in: {args.path}")
-    note(f"Dry run: {str(args.dry_run).lower()}")
-    note(f"Verbose: {str(args.verbose).lower()}")
+    note_settings(
+        ("Searching in", args.path),
+        ("Dry run", args.dry_run),
+        ("Verbose", args.verbose),
+        rule=False,
+    )
 
-    # Compare resolved paths so `--path=foo` and `--path=foo/` protect the same
-    # directory regardless of how it was spelled.
-    root_resolved = root.resolve()
+    # DELIBERATE DIVERGENCE: a dry run counts the directories it reports as
+    # already gone, so `a/b/c` previews all three. The shell version (and
+    # this one, until 3.1.0) re-checked the untouched filesystem and previewed
+    # only the leaf, under-reporting what the real run then deleted.
+    would_delete: set[Path] = set()
     deleted_count = 0
     failures = 0
 
     for directory in directories_deepest_first(root):
-        if directory.resolve() == root_resolved:
+        if directory == root:
             continue  # never touch the root the user pointed at
 
-        if not is_strictly_empty(directory):
+        if not is_strictly_empty(directory, would_delete):
             if args.verbose:
                 note(f"Skipped (not empty): {directory}")
             continue
 
         if args.dry_run:
             log(f"[DRY-RUN] Would delete: {directory}")
+            would_delete.add(directory)
         else:
-            try:
-                directory.rmdir()
-            except OSError as exc:
-                # The shell version aborted here under `set -e`; reporting and
-                # carrying on lets one unwritable directory not strand the rest.
-                warning(f"  ✗ Failed to delete {directory}: {exc}")
+            if not remove_or_warn(directory, Path.rmdir):
                 failures += 1
                 continue
             log(f"Deleted: {directory}")

package/bin/files/delete-smb-files.py

@@ -10,7 +10,7 @@ Options:
   --help        Show help
 
 Env:
-  DRY_RUN=false Opt out of the preview-only default (used by the .zshrc wrapper)
+  DRY_RUN=false Opt out of the preview-only default (used by the generated wrapper)
 """
 
 from __future__ import annotations
@@ -27,13 +27,13 @@ from utils import (
     info,
     iter_files,
     log,
-    note,
+    note_settings,
+    remove_or_warn,
     run_cli,
     scan_root,
-    warning,
 )
 
-__version__ = "2.1.0"
+__version__ = "2.1.1"
 
 PREFIX = ".smbdelete"
 
@@ -54,14 +54,10 @@ def main(argv: list[str] | None = None) -> int:
     info(f"Running command in {Path.cwd()}")
     args = parser.parse_args(argv)
 
-    note(f"Searching in: {args.path}")
-    note(f"Dry run: {str(args.dry_run).lower()}")
-
-    if not args.path:
-        warning("Error: --path is required.")
-        warning("Usage: delete-smb-files.py --path=/directory/to/scan")
-        return 1
+    note_settings(("Searching in", args.path), ("Dry run", args.dry_run), rule=False)
 
+    # An empty --path reads "--path is required", where the shell version
+    # printed "Error: --path is required." and a usage line.
     root = scan_root(args.path)
 
     info(f"Scanning for .smbdelete* files under: {args.path}")
@@ -72,9 +68,9 @@ def main(argv: list[str] | None = None) -> int:
     deleted = 0
     failures = 0
 
-    # These sidecars are hidden files, so hidden entries must NOT be skipped.
-    # `._*` filtering is likewise off - a `._.smbdeleteX` is still junk.
-    for path in iter_files(root, skip_macos_metadata=False):
+    # Case-sensitive prefix, as `find -name '.smbdelete*'` matched. That never
+    # reached a `._.smbdelete*` AppleDouble sidecar, and neither does this.
+    for path in iter_files(root):
         if not path.name.startswith(PREFIX):
             continue
 
@@ -82,13 +78,8 @@ def main(argv: list[str] | None = None) -> int:
         if args.dry_run:
             continue
 
-        try:
-            path.unlink()
-        except OSError as exc:
-            # A file held open by the SMB client fails with "Resource busy".
-            # The shell version swallowed these with `2>/dev/null || true`;
-            # naming them is strictly more useful and still non-fatal.
-            warning(f"  ✗ Could not delete {path}: {exc}")
+        # A file held open by the SMB client fails with "Resource busy".
+        if not remove_or_warn(path):
             failures += 1
             continue
         deleted += 1

package/bin/files/files-under-size.py

@@ -12,7 +12,7 @@ Options:
   --help        Show help
 
 Env:
-  DRY_RUN=false Opt out of the preview-only default (used by the .zshrc wrapper)
+  DRY_RUN=false Opt out of the preview-only default (used by the generated wrapper)
 """
 
 from __future__ import annotations
@@ -31,7 +31,9 @@ from utils import (
     iter_files,
     log,
     note,
+    note_settings,
     parse_size,
+    remove_or_warn,
     run_cli,
     scan_root,
     warning,
@@ -70,10 +72,7 @@ def main(argv: list[str] | None = None) -> int:
     info(f"Running command in {Path.cwd()}")
     args = parser.parse_args(argv)
 
-    note(f"Scanning: {args.path}")
-    note(f"Size threshold: {args.size}")
-    note(f"Dry run: {str(args.dry_run).lower()}")
-    note("----------------------------------------------------")
+    note_settings(("Scanning", args.path), ("Size threshold", args.size), ("Dry run", args.dry_run))
 
     if not args.size or not args.path:
         warning("❌ --size and --path are required")
@@ -116,12 +115,7 @@ def main(argv: list[str] | None = None) -> int:
             continue
 
         warning(f"[{index}/{total}] Deleting: {format_bytes(size)} - {path}")
-        try:
-            path.unlink()
-        except OSError as exc:
-            # The shell version aborted the run here; reporting and continuing
-            # means one busy file cannot strand the rest of the sweep.
-            warning(f"  ✗ Failed to delete {path}: {exc}")
+        if not remove_or_warn(path):
             failures += 1
 
     log("Done.")