@codebend3r/che 1.0.0 → 1.2.0

package/bin/utils.py

@@ -13,6 +13,10 @@ Everything here is standard library only, on purpose: the scripts have to run
 from a bare ``python3`` on any machine this repo is cloned to, with no venv and
 no install step.
 
+Domain helpers live beside it: git and worktree helpers in ``gitutils.py``,
+ffprobe helpers in ``media.py``, the NAS drive table and SMB mounting in
+``nas.py``.
+
 =============================================================================
 CLI conventions - shared patterns for bin/<category>/*.py
 
@@ -30,12 +34,12 @@ CLI conventions - shared patterns for bin/<category>/*.py
 from __future__ import annotations
 
 import argparse
-import json
 import os
 import re
 import shutil
 import subprocess
 import sys
+import tempfile
 from collections.abc import Callable, Iterable, Iterator, Sequence
 from fnmatch import fnmatchcase
 from pathlib import Path
@@ -52,12 +56,13 @@ YELLOW = "\033[1;33m"
 CYAN = "\033[1;36m"
 MAGENTA = "\033[1;35m"
 
-_FORCE_COLOR_OFF = {"", "0", "false", "no", "off"}
-
 
-def _color_enabled() -> bool:
+def color_enabled() -> bool:
     """Honor NO_COLOR and non-tty output the way a well-behaved CLI should.
 
+    The log helpers and :func:`paint` ask this, and so must any caller that
+    builds its own escape sequences (per-language colouring, table headers).
+
     DELIBERATE DIVERGENCE from ``utils.sh``, which always emitted escapes.
     Suppressing them when stdout is not a terminal keeps captured output clean
     for the tests and for shell pipelines. ``FORCE_COLOR`` overrides, following
@@ -66,8 +71,8 @@ def _color_enabled() -> bool:
     The tty check happens at call time, not import time, so
     ``contextlib.redirect_stdout`` and pytest's capture are both respected.
     """
-    force = os.environ.get("FORCE_COLOR")
-    if force is not None and force.lower() not in _FORCE_COLOR_OFF:
+    force = os.environ.get("FORCE_COLOR", "").strip().lower()
+    if force and force not in _FALSE_VALUES:
         return True
     if os.environ.get("NO_COLOR"):
         return False
@@ -77,11 +82,14 @@ def _color_enabled() -> bool:
         return False
 
 
-def color_enabled() -> bool:
-    """Public form of :func:`_color_enabled`, for callers that build their own
-    escape sequences (per-language colouring, table headers) and must honour
-    ``NO_COLOR`` the same way the log helpers do."""
-    return _color_enabled()
+def paint(text: str, color: str) -> str:
+    """``text`` wrapped in ``color``, or bare when colour is off.
+
+    For output assembled before it is printed - a table cell, one coloured word
+    in a plain line. An ``f"{RED}...{NC}"`` built by hand ignores ``NO_COLOR``
+    and leaks escapes into piped output.
+    """
+    return f"{color}{text}{NC}" if color_enabled() else text
 
 
 def log_color(color: str, message: str) -> None:
@@ -97,10 +105,7 @@ def log_color(color: str, message: str) -> None:
     error messages appear *before* the banner that introduced them whenever the
     output is piped to a file or a CI log.
     """
-    if _color_enabled():
-        print(f"{color}{message}{NC}", flush=True)
-    else:
-        print(message, flush=True)
+    print(paint(message, color), flush=True)
 
 
 def log(message: str) -> None:
@@ -128,6 +133,49 @@ def success(message: str) -> None:
     log_color(MAGENTA, message)
 
 
+# ---------------------------------------------------------------------------
+# Banners
+#
+# The fixed shapes scripts frame their output with, so the widths and the
+# dry-run marker stay identical from one script to the next.
+# ---------------------------------------------------------------------------
+
+_HEADING_RULE = "═" * 43
+_SETTINGS_RULE = "-" * 52
+_FOOTER_RULE = "─" * 45
+
+
+def heading(title: str, *, dry_run: bool = False) -> None:
+    """The three-line banner a script opens with, marked when it only previews."""
+    note(_HEADING_RULE)
+    note(f"{title}{' 🌵 (dry run)' if dry_run else ''}")
+    note(_HEADING_RULE)
+
+
+def note_settings(*rows: tuple[str, object], rule: bool = True) -> None:
+    """Echo a script's resolved settings as ``Label: value`` lines.
+
+    Booleans print lowercase, ``true``/``false``, as the shell versions echoed
+    them; anything else prints as-is. ``rule`` closes the block with the dashed
+    separator that sets the settings apart from the results.
+    """
+    for label, value in rows:
+        note(f"{label}: {str(value).lower() if isinstance(value, bool) else value}")
+    if rule:
+        note(_SETTINGS_RULE)
+
+
+def footer_rule() -> None:
+    """A blank line and a thin rule, opening a script's closing tally."""
+    print()
+    note(_FOOTER_RULE)
+
+
+def dry_run_complete(verb: str = "changed") -> None:
+    """The closing line of a dry run: ``Nothing was actually <verb>.``"""
+    log(f"💡 Dry run complete. Nothing was actually {verb}.")
+
+
 # ---------------------------------------------------------------------------
 # Formatting
 # ---------------------------------------------------------------------------
@@ -183,7 +231,7 @@ _FALSE_VALUES = {"false", "no", "0", "off"}
 _FALSE_SUFFIX = "-set-false-internal"
 
 
-def parse_bool(value: str | bool) -> bool:
+def parse_bool(value: str) -> bool:
     """Parse a boolean spelling.
 
     Accepts ``true|yes|1|on`` and ``false|no|0|off``, case-insensitive, and
@@ -195,9 +243,6 @@ def parse_bool(value: str | bool) -> bool:
     There ``true``/``false`` worked, ``1``/``0``/``on``/``off``/``no`` were
     "command not found", and ``yes`` invoked ``/usr/bin/yes`` and hung forever.
     """
-    if isinstance(value, bool):
-        return value
-
     lowered = value.strip().lower()
     if lowered in _TRUE_VALUES:
         return True
@@ -250,10 +295,8 @@ class BoolFlagParser(argparse.ArgumentParser):
             rewritten.append(flag if enabled else self._bool_flags[flag])
         return rewritten
 
-    def parse_args(self, args=None, namespace=None):  # type: ignore[override]
-        argv = list(sys.argv[1:] if args is None else args)
-        return super().parse_args(self._rewrite(argv), namespace)
-
+    # parse_args delegates to parse_known_args, so this one override rewrites
+    # argv for both - and only once.
     def parse_known_args(self, args=None, namespace=None):  # type: ignore[override]
         argv = list(sys.argv[1:] if args is None else args)
         return super().parse_known_args(self._rewrite(argv), namespace)
@@ -343,6 +386,28 @@ def env_bool(name: str, default: bool) -> bool:
         sys.exit(1)
 
 
+_COUNT_RE = re.compile(r"[0-9]+")
+
+
+def parse_count(raw: str, flag: str, *, minimum: int = 0) -> int:
+    """Validate an integer flag, or report why it is invalid and exit 1.
+
+    Integer flags are declared as plain strings and validated here, not with
+    ``type=int``. argparse's own conversion would own the failure and exit
+    before the shell version's message could print, and ``int()`` accepts
+    ``+5``, ``5_0`` and surrounding whitespace, all of which the shell's
+    ``^[0-9]+$`` test rejected. A leading zero is decimal: ``010`` is 10.
+
+    ``minimum`` of 1 or more reads "positive integer" in the message, 0 reads
+    "non-negative integer".
+    """
+    if not _COUNT_RE.fullmatch(raw) or int(raw) < minimum:
+        kind = "positive" if minimum > 0 else "non-negative"
+        warning(f"❌ {flag} must be a {kind} integer (got: {raw})")
+        sys.exit(1)
+    return int(raw)
+
+
 # ---------------------------------------------------------------------------
 # Subprocess
 # ---------------------------------------------------------------------------
@@ -375,7 +440,6 @@ def run(
     check: bool = True,
     capture: bool = False,
     cwd: str | Path | None = None,
-    text: bool = True,
     env: dict[str, str] | None = None,
     stdin: int | None = None,
     timeout: float | None = None,
@@ -398,12 +462,12 @@ def run(
         check=check,
         capture_output=capture,
         cwd=cwd,
-        text=text,
+        text=True,
         # errors="replace" rather than the default "strict": a single
         # non-UTF-8 byte in a child's diagnostic (a legacy-encoded title tag
         # echoed back by ffmpeg, say) would otherwise raise UnicodeDecodeError
         # and abort a whole library scan partway through.
-        errors="replace" if text else None,
+        errors="replace",
         env=merged_env,
         stdin=stdin,
         timeout=timeout,
@@ -426,20 +490,6 @@ def run_output(argv: Sequence[str], *, check: bool = True, cwd: str | Path | Non
     return (completed.stdout or "").rstrip("\n")
 
 
-def run_lines(
-    argv: Sequence[str], *, check: bool = True, cwd: str | Path | None = None
-) -> list[str]:
-    """Run a command and return stdout split into non-empty lines.
-
-    DELIBERATE DIVERGENCE: in the shell scripts these reads sat inside
-    ``< <(...)`` process substitution, whose failure does NOT trip ``set -e`` -
-    a failing ``git for-each-ref`` just looked like "no branches" and the script
-    exited 0. Here a failure raises.
-    """
-    output = run_output(argv, check=check, cwd=cwd)
-    return [line for line in output.split("\n") if line]
-
-
 def run_cli(entry: Callable[[], int]) -> None:
     """Run a script's ``main`` and translate exceptions into shell exit codes.
 
@@ -469,202 +519,20 @@ def run_cli(entry: Callable[[], int]) -> None:
         sys.exit(130)
 
 
-# ---------------------------------------------------------------------------
-# Worktrees
-#
-# A branch checked out in a linked worktree cannot be checked out, deleted or
-# reset from the main clone - git refuses with "already used by worktree".
-# That is a mechanical limit, not a conflict, so every script that touches
-# branches needs to know which ones are pinned and where.
-# ---------------------------------------------------------------------------
-
-
-def worktree_branch_map(cwd: str | Path | None = None) -> dict[str, str]:
-    """Map ``branch -> worktree path`` for every worktree with a branch checked out.
-
-    Detached worktrees are skipped (they pin no branch). The main worktree IS
-    included, because its branch is pinned for exactly the same reason.
-
-    DELIBERATE DIVERGENCE: ``utils.sh`` emitted "<branch>\t<path>" lines that
-    every caller re-parsed. A dict is the same data without the round trip, and
-    it cannot be truncated by a path containing a tab.
-    """
-    mapping: dict[str, str] = {}
-    path = ""
-    branch = ""
-
-    def flush() -> None:
-        if path and branch:
-            # First writer wins: a branch can only be pinned by one worktree,
-            # so a duplicate would mean git contradicted itself.
-            mapping.setdefault(branch, path)
-
-    for line in run_output(["git", "worktree", "list", "--porcelain"], cwd=cwd).splitlines():
-        if line.startswith("worktree "):
-            # A new record starts; flush the previous one.
-            flush()
-            path = line.removeprefix("worktree ")
-            branch = ""
-        elif line.startswith("branch refs/heads/"):
-            branch = line.removeprefix("branch refs/heads/")
-
-    flush()
-    return mapping
-
-
-def worktree_for_branch(branch: str, cwd: str | Path | None = None) -> str:
-    """The worktree path holding ``branch``, or "" when no worktree does."""
-    return worktree_branch_map(cwd).get(branch, "")
-
-
-def worktree_is_clean(path: str | Path) -> bool:
-    """True when the worktree at ``path`` has no modified or untracked files.
-
-    Ignored build output (node_modules, .next) does not count as dirty, because
-    ``git status --porcelain`` does not list ignored paths.
-    """
-    completed = run(["git", "-C", str(path), "status", "--porcelain"], check=False, capture=True)
-    # A non-zero exit means the path is not a working tree at all. Treating
-    # that as "clean" would let a caller delete a directory it never inspected.
-    if completed.returncode != 0:
-        return False
-    return not (completed.stdout or "").strip()
-
-
-def branch_is_pushed(branch: str, cwd: str | Path | None = None) -> bool:
-    """True when every commit on ``branch`` is already on its remote.
-
-    Prefers the configured upstream and falls back to ``origin/<branch>``.
-    """
-    upstream = run_output(
-        ["git", "rev-parse", "--abbrev-ref", "--symbolic-full-name", f"{branch}@{{upstream}}"],
-        check=False,
-        cwd=cwd,
-    ).strip()
-    if not upstream:
-        upstream = f"origin/{branch}"
-
-    exists = run(
-        ["git", "rev-parse", "--verify", "--quiet", upstream], check=False, capture=True, cwd=cwd
-    )
-    if exists.returncode != 0:
-        return False
-
-    ancestor = run(
-        ["git", "merge-base", "--is-ancestor", branch, upstream],
-        check=False,
-        capture=True,
-        cwd=cwd,
-    )
-    return ancestor.returncode == 0
-
-
-def worktree_paths(cwd: str | Path | None = None) -> list[str]:
-    """Every worktree path in ``git worktree list --porcelain`` order.
-
-    The first entry is always the main worktree; callers drop it themselves so
-    the distinction stays explicit at the call site.
-
-    The shell version parsed this with ``awk '{print $2}'``, which splits on
-    whitespace and so truncated any worktree path containing a space. Taking
-    the whole remainder of the line keeps such paths intact.
-    """
-    return [
-        line.removeprefix("worktree ")
-        for line in run_output(["git", "worktree", "list", "--porcelain"], cwd=cwd).splitlines()
-        if line.startswith("worktree ")
-    ]
-
-
-def main_worktree(cwd: str | Path | None = None) -> str:
-    """The main worktree's path - the first record git lists, always."""
-    paths = worktree_paths(cwd)
-    return paths[0] if paths else ""
-
-
-def find_main_branch(cwd: str | Path | None = None) -> str:
-    """The local main branch, preferring ``main`` over ``master``, or "" for neither.
-
-    Takes an explicit ``cwd`` because callers run it after moving to the main
-    worktree; relying on the process working directory would make the answer
-    depend on where the script happened to be invoked from.
-    """
-    for candidate in ("main", "master"):
-        exists = run(
-            ["git", "show-ref", "--verify", "--quiet", f"refs/heads/{candidate}"],
-            check=False,
-            capture=True,
-            cwd=cwd,
-        )
-        if exists.returncode == 0:
-            return candidate
-    return ""
-
-
-# ---------------------------------------------------------------------------
-# ffprobe
-# ---------------------------------------------------------------------------
-
-
-def ffprobe_entries(
-    path: Path,
-    entries: str,
-    *,
-    stream: str | None = None,
-    fmt: str = "csv=p=0",
-    on_error: str = "",
-) -> str:
-    """Read metadata out of a media file with ffprobe.
-
-    ``entries`` is passed straight to ``-show_entries`` (e.g.
-    ``stream=codec_name``). ``stream`` selects a stream when given (e.g.
-    ``v:0``).
-
-    Returns ``on_error`` when ffprobe itself fails, and "" when it succeeds but
-    the field is absent. Those are different situations - a corrupt file versus
-    a file with no audio track - and callers need to tell them apart.
-    """
-    argv = ["ffprobe", "-v", "error"]
-    if stream is not None:
-        argv += ["-select_streams", stream]
-    argv += ["-show_entries", entries, "-of", fmt, str(path)]
-
-    completed = run(argv, check=False, capture=True)
-    if completed.returncode != 0:
-        return on_error
-    return (completed.stdout or "").strip()
-
-
-def ffprobe_json(path: Path, argv_extra: Sequence[str]) -> dict:
-    """Run ffprobe with ``-of json`` and parse the result.
-
-    Returns an empty dict when ffprobe fails or emits unparseable output, so
-    callers can treat an unreadable file as "no streams" rather than crashing
-    partway through a large library scan.
-    """
-    argv = ["ffprobe", "-v", "error", *argv_extra, "-of", "json", str(path)]
-    completed = run(argv, check=False, capture=True)
-    if completed.returncode != 0:
-        return {}
-    try:
-        parsed = json.loads(completed.stdout or "{}")
-    except json.JSONDecodeError:
-        return {}
-    return parsed if isinstance(parsed, dict) else {}
-
-
 # ---------------------------------------------------------------------------
 # Filesystem
 # ---------------------------------------------------------------------------
 
 
-def is_macos_metadata(path: Path) -> bool:
-    """True for the AppleDouble sidecars (``._foo``) the shell scripts skipped.
+def report_walk_error(exc: OSError) -> None:
+    """``os.walk``'s ``onerror``: report an unreadable directory and carry on.
 
-    ``.DS_Store`` is deliberately not included: the scripts that skip metadata
-    are matching the ``._*`` pattern specifically.
+    find(1) printed "Permission denied" to stderr and carried on. Staying
+    silent would make a half-readable SMB share look fully scanned. stderr, not
+    the usual :func:`warning`, so these lines never interleave into output a
+    caller is piping.
     """
-    return path.name.startswith("._")
+    print(f"find: {exc.filename}: {exc.strerror}", file=sys.stderr, flush=True)
 
 
 def iter_files(
@@ -708,14 +576,7 @@ def iter_files(
     if extensions is not None:
         patterns = tuple(f"*.{ext}" if case_sensitive else f"*.{ext.lower()}" for ext in extensions)
 
-    def _on_error(exc: OSError) -> None:
-        # find(1) printed "Permission denied" to stderr and carried on. Staying
-        # silent would make a half-readable SMB share look fully scanned.
-        # stderr, not the usual warning() helper, so these lines never
-        # interleave into output a caller is piping.
-        print(f"find: {exc.filename}: {exc.strerror}", file=sys.stderr, flush=True)
-
-    for dirpath, dirnames, filenames in os.walk(root, followlinks=False, onerror=_on_error):
+    for dirpath, dirnames, filenames in os.walk(root, followlinks=False, onerror=report_walk_error):
         dirnames.sort()
         if skip_hidden:
             dirnames[:] = [d for d in dirnames if not d.startswith(".")]
@@ -770,6 +631,73 @@ def scan_root(raw: str, *, flag: str = "--path") -> Path:
     return path
 
 
+def _umask() -> int:
+    current = os.umask(0)
+    os.umask(current)
+    return current
+
+
+def atomic_write_text(path: Path, text: str, *, mode: int | None = None) -> None:
+    """Replace ``path``'s contents so a crash leaves the old file or the new one.
+
+    The text goes to a temporary file beside the target, which is then renamed
+    over it. The target is ``path`` resolved, so a symlinked dotfile (a
+    ``~/.zshrc`` that points into a dotfiles repo) has its target rewritten and
+    the link itself survives. An existing file keeps its permission bits; a new
+    one gets ``mode``, or the usual ``0o666`` less the umask where ``mkstemp``
+    alone would leave it ``0o600``.
+
+    UTF-8 with ``surrogateescape``: bytes that are not UTF-8, read the same way,
+    are written back exactly as they came in.
+
+    A hard-linked file is written in place instead. Renaming over one of its
+    names would split it from the others, which would keep the old contents.
+    """
+    target = path.resolve()
+    target.parent.mkdir(parents=True, exist_ok=True)
+
+    if target.exists() and target.stat().st_nlink > 1:
+        with target.open("w", encoding="utf-8", errors="surrogateescape") as handle:
+            handle.write(text)
+        if mode is not None:
+            target.chmod(mode)
+        return
+
+    descriptor, temp_name = tempfile.mkstemp(dir=target.parent, prefix=f".{target.name}.")
+    temp = Path(temp_name)
+    try:
+        with os.fdopen(descriptor, "w", encoding="utf-8", errors="surrogateescape") as handle:
+            handle.write(text)
+            handle.flush()
+            os.fsync(handle.fileno())
+        if mode is not None:
+            temp.chmod(mode)
+        elif target.exists():
+            shutil.copymode(target, temp)
+        else:
+            temp.chmod(0o666 & ~_umask())
+        temp.replace(target)
+    except BaseException:
+        temp.unlink(missing_ok=True)
+        raise
+
+
+def remove_or_warn(path: Path, remove: Callable[[Path], None] = Path.unlink) -> bool:
+    """Delete ``path`` (``remove=Path.rmdir`` for a directory), or say why not.
+
+    Returns whether it went. A failure is reported and left to the caller to
+    count: the shell versions aborted the whole run here under ``set -e`` (or,
+    in ``delete-smb-files``, hid it with ``2>/dev/null``), and on a NAS one busy
+    file should not strand the rest of a sweep.
+    """
+    try:
+        remove(path)
+    except OSError as exc:
+        warning(f"  ✗ Failed to delete {path}: {exc}")
+        return False
+    return True
+
+
 def normalize_extensions(raw: str, *, flag: str = "--ext") -> list[str]:
     """Split a comma-separated extension list, preserving glob metacharacters.