@codebend3r/che 1.0.0

package/bin/files/compress-folders.py

@@ -0,0 +1,188 @@
+#!/usr/bin/env python3
+"""📦 Create a max-compression .zip of every immediate subfolder of a path.
+
+Each ``<folder>`` becomes ``<folder>.zip`` alongside it.
+
+Usage:
+  compress-folders.py --path=/dir [--dry-run] [--verbose]
+
+Options:
+  --path=DIR    Parent directory whose subfolders should be zipped (required)
+  --dry-run     Print what would be zipped, change nothing
+  --verbose     Show per-file progress
+  --help        Show help
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import zipfile
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from utils import (
+    add_bool_flag,
+    build_parser,
+    info,
+    log,
+    note,
+    run_cli,
+    scan_root,
+    success,
+    warning,
+)
+
+__version__ = "3.0.0"
+
+
+def _walk_entries(folder: Path) -> list[tuple[Path, str]]:
+    """Every entry to store, as ``(source_path, archive_name)`` pairs.
+
+    Symlinks are FOLLOWED, matching ``zip -r`` - which, contrary to a common
+    assumption, dereferences by default and only stores links as links with
+    ``-y``. Skipping them would silently drop file content from the archive.
+
+    Directory inodes already visited are not re-entered, so a symlink loop
+    cannot hang the walk. ``zip`` has its own loop protection; this is ours.
+    """
+    parent = folder.parent
+    entries: list[tuple[Path, str]] = [(folder, str(folder.relative_to(parent)))]
+    seen: set[tuple[int, int]] = set()
+
+    for dirpath, dirnames, filenames in os.walk(folder, followlinks=True):
+        directory = Path(dirpath)
+
+        try:
+            stat = directory.stat()
+        except OSError:
+            continue
+        key = (stat.st_dev, stat.st_ino)
+        if key in seen:
+            dirnames[:] = []
+            continue
+        seen.add(key)
+
+        dirnames.sort()
+        filenames.sort()
+
+        for name in dirnames:
+            child = directory / name
+            entries.append((child, str(child.relative_to(parent))))
+        for name in filenames:
+            child = directory / name
+            entries.append((child, str(child.relative_to(parent))))
+
+    return entries
+
+
+def zip_folder(folder: Path, archive: Path, *, verbose: bool) -> None:
+    """Write ``folder`` into ``archive`` with deflate level 9.
+
+    Paths are stored relative to the folder's *parent*, so the archive expands
+    to ``<folder>/...``, and the top-level directory entry is written first -
+    without it an empty folder would archive to nothing at all, and its mode
+    bits would be lost on restore.
+
+    The archive is written to a temporary name and moved into place, so an
+    interrupted run cannot leave a half-written .zip shadowing a good one.
+    Note this always rewrites from scratch: unlike ``zip -FS`` sync mode it
+    recompresses unchanged files rather than copying them across.
+
+    Filenames are stored with the UTF-8 flag bit set, which ``zip`` does not
+    do - non-ASCII names come back correctly instead of as mojibake.
+    """
+    temp_archive = archive.with_name(archive.name + ".partial")
+
+    try:
+        with zipfile.ZipFile(
+            temp_archive, "w", compression=zipfile.ZIP_DEFLATED, compresslevel=9
+        ) as zf:
+            for source, arcname in _walk_entries(folder):
+                if verbose and source.is_file():
+                    info(f"    + {arcname}")
+                zf.write(source, arcname)
+        temp_archive.replace(archive)
+    except BaseException:
+        # Also fires on KeyboardInterrupt and SystemExit, deliberately: the
+        # point is to never leave a .partial behind. Always re-raises.
+        temp_archive.unlink(missing_ok=True)
+        raise
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser(
+        prog="compress-folders",
+        description="📦 Create a max-compression .zip of every immediate subfolder of --path.",
+    )
+    parser.add_argument(
+        "--path", default="", metavar="DIR", help="Parent directory to zip subfolders of (required)"
+    )
+    add_bool_flag(parser, "--dry-run", help="Print what would be zipped, change nothing")
+    add_bool_flag(parser, "--verbose", help="Show per-file progress")
+    args = parser.parse_args(argv)
+
+    if not args.path:
+        warning("❌ --path is required")
+        parser.print_help()
+        return 1
+
+    root = scan_root(args.path)
+
+    header_suffix = " 🌵 (dry run)" if args.dry_run else ""
+    note("═══════════════════════════════════════════")
+    note(f"📦  compress-folders{header_suffix}")
+    note("═══════════════════════════════════════════")
+    note(f"Parent: {root}")
+
+    compressed = 0
+    skipped = 0
+
+    # Matches the shell version's `for dir in "$ROOT_DIR"/*/` glob: dotted
+    # directories are skipped (no `dotglob`), and a symlink to a directory IS
+    # included, because `*/` matches it.
+    folders = sorted(
+        path for path in root.iterdir() if path.is_dir() and not path.name.startswith(".")
+    )
+
+    for folder in folders:
+        archive = folder.with_name(folder.name + ".zip")
+
+        if args.dry_run:
+            info(f"  🪄 Would zip: {folder.name} → {folder.name}.zip")
+            compressed += 1
+            continue
+
+        info(f"📦 Compressing '{folder.name}'...")
+        try:
+            zip_folder(folder, archive, verbose=args.verbose)
+        except (OSError, ValueError) as exc:
+            # ValueError covers a file whose size changes mid-write and the
+            # UnicodeEncodeError raised for surrogate bytes in names off an
+            # SMB mount. The shell version isolated each folder in a subshell,
+            # so one bad folder never stopped the batch.
+            warning(f"  ❌ Failed: {archive} ({exc})")
+            skipped += 1
+            continue
+        success(f"  ✅ {folder.name}.zip")
+        compressed += 1
+
+    print()
+    note("─────────────────────────────────────────────")
+    if args.dry_run:
+        success(f"🌵 Would compress: {compressed} folder(s)")
+        log("💡 Dry run complete. Nothing was actually changed.")
+        return 0
+
+    success(f"✅ Compressed: {compressed}")
+    if skipped:
+        warning(f"❌ Failed:     {skipped}")
+        return 1
+
+    log("🎉 Compression complete.")
+    return 0
+
+
+if __name__ == "__main__":
+    run_cli(main)

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

@@ -0,0 +1,108 @@
+#!/usr/bin/env python3
+"""🗑️  Delete every file under a path matching a set of extensions.
+
+Usage:
+  delete-by-ext.py --path=/dir [--ext=jpg,png,mp4] [--dry-run] [--verbose]
+
+Options:
+  --path=DIR    Directory to scan (required)
+  --ext=LIST    Comma-separated extensions, no dots. Glob metacharacters work,
+                so --ext=mp* matches mp4/mp3/mpg
+                (default: m3u,nfo,sfv,jpg,png,txt,log,cue,srr)
+  --dry-run     Print what would be deleted, change nothing
+  --verbose     Extra detail
+  --help        Show help
+
+Env:
+  DRY_RUN=false Opt out of the preview-only default (used by the .zshrc wrapper)
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from utils import (
+    add_bool_flag,
+    build_parser,
+    env_bool,
+    info,
+    iter_files,
+    log,
+    normalize_extensions,
+    note,
+    run_cli,
+    scan_root,
+    warning,
+)
+
+__version__ = "2.2.0"
+
+DEFAULT_EXTENSIONS = ("m3u", "nfo", "sfv", "jpg", "png", "txt", "log", "cue", "srr")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser(
+        prog="delete-by-ext",
+        description="🗑️  Delete files under a path matching a set of extensions.",
+    )
+    parser.add_argument("--path", default="", metavar="DIR", help="Directory to scan (required)")
+    parser.add_argument(
+        "--ext",
+        default=",".join(DEFAULT_EXTENSIONS),
+        metavar="LIST",
+        help=f"Comma-separated extensions (default: {','.join(DEFAULT_EXTENSIONS)})",
+    )
+    add_bool_flag(
+        parser,
+        "--dry-run",
+        default=env_bool("DRY_RUN", True),
+        help="Print what would be deleted, change nothing",
+    )
+    add_bool_flag(parser, "--verbose", help="Extra detail")
+
+    info(f"Running command in {Path.cwd()}")
+    args = parser.parse_args(argv)
+
+    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("----------------------------------------------------")
+
+    if not extensions:
+        warning("--ext is required")
+        return 1
+
+    root = scan_root(args.path)
+
+    failures = 0
+
+    # macOS ._ sidecars are NOT skipped: the shell version deleted them when
+    # they matched, and leaving them orphaned after their parent file is gone
+    # is worse than deleting them.
+    for path in iter_files(root, extensions=extensions, skip_macos_metadata=False):
+        if args.dry_run:
+            info(f"[DRY RUN] Would delete: {path}")
+            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}")
+            failures += 1
+
+    log("Completed.")
+    return 1 if failures else 0
+
+
+if __name__ == "__main__":
+    run_cli(main)

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

@@ -0,0 +1,136 @@
+#!/usr/bin/env python3
+"""🧹 Delete truly-empty directories under a path, cascading upwards.
+
+Only *strictly* empty directories are removed. A folder holding nothing but
+``.DS_Store``, ``._*`` or ``.git`` is intentionally left alone - a recursive
+delete would silently wipe them.
+
+Usage:
+  delete-empty-folders.py --path=/dir [--dry-run] [--verbose]
+
+Options:
+  --path=DIR    Directory to scan (required)
+  --dry-run     Print what would be deleted, change nothing
+  --verbose     Report skipped non-empty directories too
+  --help        Show help
+
+Env:
+  DRY_RUN=false Opt out of the preview-only default (used by the .zshrc wrapper)
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from utils import (
+    add_bool_flag,
+    build_parser,
+    env_bool,
+    info,
+    log,
+    note,
+    run_cli,
+    scan_root,
+    warning,
+)
+
+__version__ = "3.0.0"
+
+
+def directories_deepest_first(root: Path) -> list[Path]:
+    """Every directory under ``root``, children before parents.
+
+    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.
+    """
+
+    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) -> bool:
+    """True only when the directory has no entries at all, hidden included."""
+    try:
+        next(path.iterdir())
+    except StopIteration:
+        return True
+    except OSError:
+        return False
+    return False
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser(
+        prog="delete-empty-folders",
+        description="🧹 Delete truly-empty directories under a path, cascading upwards.",
+    )
+    parser.add_argument("--path", default="", metavar="DIR", help="Directory to scan (required)")
+    add_bool_flag(
+        parser,
+        "--dry-run",
+        default=env_bool("DRY_RUN", True),
+        help="Print what would be deleted, change nothing",
+    )
+    add_bool_flag(parser, "--verbose", help="Report skipped non-empty directories too")
+
+    info(f"Running command in {Path.cwd()}")
+    args = parser.parse_args(argv)
+
+    if not args.path:
+        warning("Error: --path is required.")
+        return 1
+
+    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()}")
+
+    # Compare resolved paths so `--path=foo` and `--path=foo/` protect the same
+    # directory regardless of how it was spelled.
+    root_resolved = root.resolve()
+    deleted_count = 0
+    failures = 0
+
+    for directory in directories_deepest_first(root):
+        if directory.resolve() == root_resolved:
+            continue  # never touch the root the user pointed at
+
+        if not is_strictly_empty(directory):
+            if args.verbose:
+                note(f"Skipped (not empty): {directory}")
+            continue
+
+        if args.dry_run:
+            log(f"[DRY-RUN] Would delete: {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}")
+                failures += 1
+                continue
+            log(f"Deleted: {directory}")
+        deleted_count += 1
+
+    log(f"📊 Total deleted directories: {deleted_count}")
+    return 1 if failures else 0
+
+
+if __name__ == "__main__":
+    run_cli(main)

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

@@ -0,0 +1,105 @@
+#!/usr/bin/env python3
+"""🧽 Delete the ``.smbdelete*`` turds an SMB share leaves behind.
+
+Usage:
+  delete-smb-files.py --path=/dir [--dry-run]
+
+Options:
+  --path=DIR    Directory to scan (required)
+  --dry-run     List what would be deleted, change nothing
+  --help        Show help
+
+Env:
+  DRY_RUN=false Opt out of the preview-only default (used by the .zshrc wrapper)
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from utils import (
+    add_bool_flag,
+    build_parser,
+    env_bool,
+    info,
+    iter_files,
+    log,
+    note,
+    run_cli,
+    scan_root,
+    warning,
+)
+
+__version__ = "2.1.0"
+
+PREFIX = ".smbdelete"
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser(
+        prog="delete-smb-files",
+        description="🧽 Delete .smbdelete* files left behind by an SMB share.",
+    )
+    parser.add_argument("--path", default="", metavar="DIR", help="Directory to scan (required)")
+    add_bool_flag(
+        parser,
+        "--dry-run",
+        default=env_bool("DRY_RUN", True),
+        help="List what would be deleted, change nothing",
+    )
+
+    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
+
+    root = scan_root(args.path)
+
+    info(f"Scanning for .smbdelete* files under: {args.path}")
+
+    if args.dry_run:
+        info("Dry run mode: no files will be deleted.")
+
+    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):
+        if not path.name.startswith(PREFIX):
+            continue
+
+        print(path, flush=True)
+        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}")
+            failures += 1
+            continue
+        deleted += 1
+
+    if not args.dry_run:
+        # Summary line the shell version did not print; a sweep that silently
+        # deleted nothing is indistinguishable from one that could not run.
+        log(f"📊 Deleted {deleted} file(s).")
+
+    return 1 if failures else 0
+
+
+if __name__ == "__main__":
+    run_cli(main)

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

@@ -0,0 +1,132 @@
+#!/usr/bin/env python3
+"""📉 Find (and optionally delete) video files at or under a size threshold.
+
+Usage:
+  files-under-size.py --path=/dir --size=1MB [--dry-run]
+
+Options:
+  --path=DIR    Directory to scan (required)
+  --size=SIZE   Threshold, e.g. 500k / 1MB / 2GiB (required, binary units,
+                bytes through gigabytes only)
+  --dry-run     List what would be deleted, change nothing
+  --help        Show help
+
+Env:
+  DRY_RUN=false Opt out of the preview-only default (used by the .zshrc wrapper)
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from utils import (
+    add_bool_flag,
+    build_parser,
+    env_bool,
+    format_bytes,
+    info,
+    iter_files,
+    log,
+    note,
+    parse_size,
+    run_cli,
+    scan_root,
+    warning,
+)
+
+__version__ = "2.2.0"
+
+VIDEO_EXTENSIONS = (
+    "mp4",
+    "mkv",
+    "avi",
+    "mov",
+    "flv",
+    "wmv",
+    "webm",
+    "mpeg",
+    "mpg",
+    "m4v",
+)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser(
+        prog="files-under-size",
+        description="📉 Find video files at or under a size threshold.",
+    )
+    parser.add_argument("--path", default="", metavar="DIR", help="Directory to scan (required)")
+    parser.add_argument("--size", default="", metavar="SIZE", help="Threshold, e.g. 1MB (required)")
+    add_bool_flag(
+        parser,
+        "--dry-run",
+        default=env_bool("DRY_RUN", True),
+        help="List what would be deleted, change nothing",
+    )
+
+    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("----------------------------------------------------")
+
+    if not args.size or not args.path:
+        warning("❌ --size and --path are required")
+        warning("📋 Usage: files-under-size.py --path=/dir --size=1MB [--dry-run]")
+        return 1
+
+    try:
+        limit_bytes = parse_size(args.size)
+    except ValueError as exc:
+        warning(f"❌ {exc}")
+        return 1
+
+    root = scan_root(args.path)
+
+    # The shell version used `find -size -Nc` with N = limit + 1, which selects
+    # files of AT MOST `limit` bytes. Keep the inclusive comparison.
+    matches: list[tuple[Path, int]] = []
+    for path in iter_files(root, extensions=VIDEO_EXTENSIONS, skip_macos_metadata=False):
+        try:
+            size = path.stat().st_size
+        except OSError:
+            continue
+        if size <= limit_bytes:
+            matches.append((path, size))
+
+    total = len(matches)
+    if total == 0:
+        log(f"No matching video files ≤ {args.size} ({limit_bytes} bytes).")
+        return 0
+
+    info(f"Found {total} file(s) ≤ {args.size} ({limit_bytes} bytes)")
+    note(f"Threshold: {limit_bytes:,} bytes ({args.size})")
+
+    failures = 0
+
+    for index, (path, size) in enumerate(matches, start=1):
+        log(f"File size: {format_bytes(size)}")
+        if args.dry_run:
+            warning(f"[{index}/{total}] Would delete: {format_bytes(size)} - {path}")
+            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}")
+            failures += 1
+
+    log("Done.")
+    return 1 if failures else 0
+
+
+if __name__ == "__main__":
+    run_cli(main)