dktcli 1.0.0__py3-none-any.whl

devkittools/utils.py

@@ -0,0 +1,561 @@
+"""Shared helpers for devkittools."""
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+import threading
+import time
+from pathlib import Path
+from typing import List, Optional, Sequence, Tuple
+
+
+class DktError(Exception):
+    """A user-facing error. Printed without a traceback."""
+
+
+# ----------------------------------------------------------------- console
+
+_COLOR = False
+_CODES = {
+    "black": "30", "red": "31", "green": "32", "yellow": "33", "blue": "34",
+    "magenta": "35", "cyan": "36", "white": "37", "gray": "90",
+    "bred": "91", "bgreen": "92", "byellow": "93", "bblue": "94",
+    "bmagenta": "95", "bcyan": "96", "bwhite": "97",
+    "bold": "1", "dim": "2", "italic": "3", "underline": "4", "reverse": "7",
+}
+
+
+def setup_console() -> None:
+    """Make output UTF-8 safe and enable ANSI colors when possible."""
+    global _COLOR
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            stream.reconfigure(encoding="utf-8", errors="replace")  # type: ignore[attr-defined]
+        except Exception:
+            pass
+    if os.environ.get("NO_COLOR"):
+        _COLOR = False
+        return
+    if sys.stdout.isatty():
+        if os.name == "nt":
+            os.system("")  # enables ANSI escape processing on Windows 10+
+        _COLOR = True
+
+
+def c(text, color: str) -> str:
+    """Colorize text. `color` may combine styles: c("hi", "bold cyan")."""
+    if not _COLOR:
+        return str(text)
+    codes = ";".join(_CODES[x] for x in color.split())
+    return "\033[%sm%s\033[0m" % (codes, text)
+
+
+def info(msg: str = "") -> None:
+    """Status output goes to stderr so stdout stays clean for piping."""
+    print(msg, file=sys.stderr)
+
+
+def print_table(headers: Sequence[str], rows: Sequence[Sequence[object]], indent: str = "  ") -> None:
+    widths = [len(h) for h in headers]
+    srows = [[str(x) for x in r] for r in rows]
+    for r in srows:
+        for i, cell in enumerate(r):
+            widths[i] = max(widths[i], len(cell))
+    head = "  ".join(h.ljust(widths[i]) for i, h in enumerate(headers))
+    print(indent + c(head, "bold"))
+    print(indent + c("  ".join("-" * w for w in widths), "dim"))
+    for r in srows:
+        print(indent + "  ".join(cell.ljust(widths[i]) for i, cell in enumerate(r)))
+
+
+def bar(value: float, maximum: float, width: int = 20) -> str:
+    if maximum <= 0:
+        filled = 0
+    else:
+        filled = int(round(width * value / maximum))
+    return "█" * filled + "░" * (width - filled)
+
+
+def human_size(n: float) -> str:
+    for unit in ("B", "KB", "MB", "GB"):
+        if n < 1024 or unit == "GB":
+            return ("%d %s" % (n, unit)) if unit == "B" else ("%.1f %s" % (n, unit))
+        n /= 1024.0
+    return "%d B" % n
+
+
+def human_num(n: int) -> str:
+    return "{:,}".format(n)
+
+
+def str2bool(value) -> bool:
+    if isinstance(value, bool):
+        return value
+    v = str(value).strip().lower()
+    if v in ("1", "true", "t", "yes", "y", "on"):
+        return True
+    if v in ("0", "false", "f", "no", "n", "off", ""):
+        return False
+    raise DktError("Expected true/false but got '%s'" % value)
+
+
+# ----------------------------------------------------------------- processes
+
+def decode_output(data: bytes) -> str:
+    if os.name == "nt":
+        try:
+            return data.decode("oem", errors="replace")
+        except LookupError:
+            pass
+    return data.decode("utf-8", errors="replace")
+
+
+def run_capture(cmd: Sequence[str]) -> Tuple[int, str, str]:
+    """Run a command, return (returncode, stdout, stderr). Never raises on non-zero."""
+    try:
+        r = subprocess.run(list(cmd), stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+                           stdin=subprocess.DEVNULL)
+    except FileNotFoundError:
+        raise DktError("Command not found: %s" % cmd[0])
+    return r.returncode, decode_output(r.stdout), decode_output(r.stderr)
+
+
+# ----------------------------------------------------------------- folders / git
+
+def resolve_folder(value: Optional[str]) -> Path:
+    p = Path(value).expanduser() if value else Path.cwd()
+    p = p.resolve()
+    if not p.is_dir():
+        raise DktError("Folder not found: %s" % p)
+    return p
+
+
+def git(folder: Path, *args: str, check: bool = True) -> str:
+    """Run git inside `folder` and return stdout (UTF-8)."""
+    cmd = ["git", "-C", str(folder), "-c", "core.quotepath=false"] + list(args)
+    try:
+        r = subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+                           stdin=subprocess.DEVNULL)
+    except FileNotFoundError:
+        raise DktError("git is not installed or not on PATH. Get it at https://git-scm.com")
+    if r.returncode != 0:
+        if check:
+            msg = r.stderr.decode("utf-8", errors="replace").strip()
+            raise DktError(msg or "git %s failed" % " ".join(args))
+        return ""
+    return r.stdout.decode("utf-8", errors="replace")
+
+
+def is_git_repo(folder: Path) -> bool:
+    try:
+        return git(folder, "rev-parse", "--is-inside-work-tree", check=False).strip() == "true"
+    except DktError:
+        return False
+
+
+def require_git_repo(folder: Path) -> None:
+    if not is_git_repo(folder):
+        raise DktError("%s is not inside a git repository." % folder)
+
+
+IGNORE_DIRS = {
+    ".git", ".hg", ".svn", "node_modules", "__pycache__", ".venv", "venv", "env",
+    ".idea", ".vscode", "dist", "build", ".mypy_cache", ".pytest_cache", ".tox",
+    "target", ".next", ".gradle", ".cache", "coverage",
+}
+
+
+def list_project_files(folder: Path) -> List[Path]:
+    """Relative paths of project files. Respects .gitignore inside git repos."""
+    if is_git_repo(folder):
+        try:
+            r = subprocess.run(
+                ["git", "-C", str(folder), "ls-files", "-co", "--exclude-standard", "-z"],
+                stdout=subprocess.PIPE, stderr=subprocess.PIPE, stdin=subprocess.DEVNULL, check=True)
+            names = [n for n in r.stdout.decode("utf-8", errors="replace").split("\0") if n]
+            files = [Path(n) for n in names if (folder / n).is_file()]
+            return sorted(set(files))
+        except Exception:
+            pass
+    files = []
+    for root, dirs, fnames in os.walk(str(folder)):
+        dirs[:] = [d for d in dirs if d not in IGNORE_DIRS and not d.endswith(".egg-info")]
+        for f in fnames:
+            files.append(Path(root, f).relative_to(folder))
+    return sorted(files)
+
+
+def is_binary_chunk(chunk: bytes) -> bool:
+    return b"\0" in chunk
+
+
+# ----------------------------------------------------------------- clipboard
+
+def copy_to_clipboard(text: str) -> bool:
+    try:
+        if os.name == "nt":
+            with tempfile.NamedTemporaryFile("w", suffix=".txt", delete=False, encoding="utf-8") as f:
+                f.write(text)
+                tmp = f.name
+            try:
+                cmd = "Get-Content -Raw -Encoding UTF8 -LiteralPath '%s' | Set-Clipboard" % tmp
+                r = subprocess.run(["powershell", "-NoProfile", "-Command", cmd],
+                                   stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+                return r.returncode == 0
+            finally:
+                try:
+                    os.unlink(tmp)
+                except OSError:
+                    pass
+        if sys.platform == "darwin" and shutil.which("pbcopy"):
+            subprocess.run(["pbcopy"], input=text.encode("utf-8"), check=True)
+            return True
+        for tool in (["wl-copy"], ["xclip", "-selection", "clipboard"], ["xsel", "--clipboard", "--input"]):
+            if shutil.which(tool[0]):
+                subprocess.run(tool, input=text.encode("utf-8"), check=True)
+                return True
+    except Exception:
+        return False
+    return False
+
+
+# ================================================================= UI toolkit
+# Everything below is pure stdlib: boxes, banners, spinners, prompts, config.
+
+_ANSI_RE = re.compile(r"\033\[[0-9;]*m")
+
+
+def color_enabled() -> bool:
+    return _COLOR
+
+
+def vlen(text: str) -> int:
+    """Visible length of a string (ANSI escapes removed)."""
+    return len(_ANSI_RE.sub("", text))
+
+
+def strip_ansi(text: str) -> str:
+    return _ANSI_RE.sub("", text)
+
+
+def term_width(default: int = 80) -> int:
+    try:
+        return max(40, min(shutil.get_terminal_size((default, 24)).columns, 140))
+    except Exception:
+        return default
+
+
+_UNICODE_SYMS = {
+    "ok": "✔", "fail": "✘", "warn": "▲", "arrow": "➜", "dot": "•", "info": "ℹ",
+    "tl": "╭", "tr": "╮", "bl": "╰", "br": "╯", "h": "─", "v": "│",
+    "t": "├", "l": "└", "pipe": "│",
+}
+_ASCII_SYMS = {
+    "ok": "+", "fail": "x", "warn": "!", "arrow": ">", "dot": "*", "info": "i",
+    "tl": "+", "tr": "+", "bl": "+", "br": "+", "h": "-", "v": "|",
+    "t": "|", "l": "`", "pipe": "|",
+}
+
+
+def sym(name: str) -> str:
+    if os.environ.get("DKT_ASCII"):
+        return _ASCII_SYMS[name]
+    enc = (getattr(sys.stdout, "encoding", None) or "").lower()
+    return (_UNICODE_SYMS if "utf" in enc else _ASCII_SYMS)[name]
+
+
+def ok(msg: str) -> None:
+    print("%s %s" % (c(sym("ok"), "bgreen"), msg))
+
+
+def warn(msg: str) -> None:
+    print("%s %s" % (c(sym("warn"), "byellow"), msg))
+
+
+def fail(msg: str) -> None:
+    print("%s %s" % (c(sym("fail"), "bred"), msg))
+
+
+def note(msg: str) -> None:
+    print("%s %s" % (c(sym("info"), "bcyan"), msg))
+
+
+def heading(title: str, subtitle: str = "") -> None:
+    """Section heading with a rule underneath."""
+    print()
+    print("  " + c(title, "bold bcyan") + ((" " + c(subtitle, "gray")) if subtitle else ""))
+    print("  " + c(sym("h") * min(term_width() - 4, max(vlen(title) + vlen(subtitle) + 1, 24)), "gray"))
+
+
+def rule(title: str = "", width: Optional[int] = None) -> str:
+    width = width or term_width() - 2
+    if not title:
+        return c(sym("h") * width, "gray")
+    left = sym("h") * 3 + " "
+    right = " " + sym("h") * max(3, width - vlen(title) - 5)
+    return c(left, "gray") + c(title, "bold") + c(right, "gray")
+
+
+def box(title: str, lines: Sequence[str], color: str = "bcyan", width: Optional[int] = None) -> None:
+    """Draw a rounded box around lines of text."""
+    lines = [str(x) for x in lines]
+    inner = max([vlen(x) for x in lines] + [vlen(title) + 2, 20])
+    if width:
+        inner = max(inner, width - 4)
+    inner = min(inner, term_width() - 4)
+    top_title = (" " + title + " ") if title else ""
+    top = c(sym("tl") + sym("h"), color) + c(top_title, "bold " + color) + \
+        c(sym("h") * max(0, inner + 1 - vlen(top_title)) + sym("tr"), color)
+    print(top)
+    for ln in lines:
+        pad = " " * max(0, inner - vlen(ln))
+        print(c(sym("v"), color) + " " + ln + pad + " " + c(sym("v"), color))
+    print(c(sym("bl") + sym("h") * (inner + 2) + sym("br"), color))
+
+
+def kv(rows: Sequence[Tuple[str, object]], indent: str = "  ", key_color: str = "gray") -> None:
+    """Aligned key/value list."""
+    if not rows:
+        return
+    w = max(len(str(k)) for k, _ in rows)
+    for k, v in rows:
+        print("%s%s  %s" % (indent, c(str(k).ljust(w), key_color), v))
+
+
+_GRADIENT = (51, 45, 39, 33, 99, 135, 171, 207)
+
+
+def gradient(lines: Sequence[str]) -> List[str]:
+    """Color lines with a cyan -> magenta gradient (256-color terminals)."""
+    if not _COLOR:
+        return list(lines)
+    out = []
+    n = max(1, len(lines) - 1)
+    for i, ln in enumerate(lines):
+        code = _GRADIENT[int(round(i / n * (len(_GRADIENT) - 1)))]
+        out.append("\033[38;5;%dm%s\033[0m" % (code, ln))
+    return out
+
+
+_LOGO = [
+    r"  ____  _  _______ ",
+    r" |  _ \| |/ /_   _|",
+    r" | | | | ' /  | |  ",
+    r" | |_| | . \  | |  ",
+    r" |____/|_|\_\ |_|  ",
+]
+
+
+def banner(subtitle: str = "") -> None:
+    from . import __version__
+    logo = gradient(_LOGO)
+    side = [
+        "",
+        c("devkittools", "bold") + " " + c("v" + __version__, "gray"),
+        c("the developer's swiss army knife", "gray"),
+        c(subtitle, "bcyan") if subtitle else "",
+        "",
+    ]
+    print()
+    for a, b in zip(logo, side):
+        print(a + "   " + b)
+    print()
+
+
+def table(headers: Sequence[str], rows: Sequence[Sequence[object]], indent: str = "  ") -> None:
+    """Like print_table but ANSI-aware so cells can be colored."""
+    srows = [[str(x) for x in r] for r in rows]
+    widths = [vlen(h) for h in headers]
+    for r in srows:
+        for i, cell in enumerate(r):
+            widths[i] = max(widths[i], vlen(cell))
+    pad = lambda s, w: s + " " * (w - vlen(s))  # noqa: E731
+    print(indent + c("  ".join(pad(h, widths[i]) for i, h in enumerate(headers)), "bold"))
+    print(indent + c("  ".join(sym("h") * w for w in widths), "gray"))
+    for r in srows:
+        print(indent + "  ".join(pad(cell, widths[i]) for i, cell in enumerate(r)))
+
+
+class Spinner:
+    """`with Spinner("working..."):` - animated on a TTY, silent otherwise."""
+
+    FRAMES_U = "⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏"
+    FRAMES_A = "|/-\\"
+
+    def __init__(self, text: str = "working"):
+        self.text = text
+        self._stop = threading.Event()
+        self._thread = None  # type: Optional[threading.Thread]
+        self._active = False
+
+    def update(self, text: str) -> None:
+        self.text = text
+
+    def _spin(self) -> None:
+        frames = self.FRAMES_U if sym("ok") != "+" else self.FRAMES_A
+        i = 0
+        while not self._stop.is_set():
+            sys.stderr.write("\r  %s %s\033[K" % (c(frames[i % len(frames)], "bcyan"), self.text))
+            sys.stderr.flush()
+            i += 1
+            time.sleep(0.08)
+
+    def __enter__(self):
+        if _COLOR and sys.stderr.isatty():
+            self._active = True
+            self._thread = threading.Thread(target=self._spin, daemon=True)
+            self._thread.start()
+        return self
+
+    def __exit__(self, *exc):
+        if self._active and self._thread:
+            self._stop.set()
+            self._thread.join()
+            sys.stderr.write("\r\033[K")
+            sys.stderr.flush()
+        return False
+
+
+# ----------------------------------------------------------------- prompts
+
+def is_interactive() -> bool:
+    try:
+        return sys.stdin.isatty() and sys.stdout.isatty()
+    except Exception:
+        return False
+
+
+def ask(prompt: str, default: Optional[str] = None) -> str:
+    if not is_interactive():
+        return default or ""
+    suffix = " [%s]" % default if default else ""
+    try:
+        val = input("%s %s%s: " % (c(sym("arrow"), "bcyan"), prompt, c(suffix, "gray"))).strip()
+    except EOFError:
+        return default or ""
+    return val or (default or "")
+
+
+def confirm(prompt: str, default: bool = False) -> bool:
+    if not is_interactive():
+        return default
+    hint = "Y/n" if default else "y/N"
+    try:
+        val = input("%s %s %s " % (c("?", "bmagenta"), prompt, c("(%s)" % hint, "gray"))).strip().lower()
+    except EOFError:
+        return default
+    if not val:
+        return default
+    return val in ("y", "yes")
+
+
+# ----------------------------------------------------------------- input helpers
+
+def paste_from_clipboard() -> Optional[str]:
+    try:
+        if os.name == "nt":
+            r = subprocess.run(["powershell", "-NoProfile", "-Command", "Get-Clipboard -Raw"],
+                               stdout=subprocess.PIPE, stderr=subprocess.DEVNULL)
+            return r.stdout.decode("utf-8", errors="replace").rstrip("\r\n") if r.returncode == 0 else None
+        if sys.platform == "darwin" and shutil.which("pbpaste"):
+            return subprocess.run(["pbpaste"], stdout=subprocess.PIPE).stdout.decode("utf-8", errors="replace")
+        for tool in (["wl-paste", "-n"], ["xclip", "-selection", "clipboard", "-o"], ["xsel", "--clipboard", "--output"]):
+            if shutil.which(tool[0]):
+                return subprocess.run(tool, stdout=subprocess.PIPE, stderr=subprocess.DEVNULL).stdout.decode("utf-8", errors="replace")
+    except Exception:
+        return None
+    return None
+
+
+def read_input(text: Optional[str] = None, file: Optional[str] = None, paste: bool = False,
+               what: str = "input") -> str:
+    """Get text from (in order): --file, positional text, --paste, piped stdin."""
+    if file:
+        p = Path(file).expanduser()
+        if not p.is_file():
+            raise DktError("File not found: %s" % p)
+        return p.read_text(encoding="utf-8", errors="replace")
+    if text is not None and text != "-":
+        return text
+    if paste:
+        got = paste_from_clipboard()
+        if got is None:
+            raise DktError("Could not read the clipboard on this system.")
+        return got
+    if text == "-" or not sys.stdin.isatty():
+        return sys.stdin.read()
+    raise DktError("No %s given. Pass it as an argument, use --file/--paste, or pipe it in." % what)
+
+
+def output_result(text: str, copy: bool = False, quiet: bool = False) -> None:
+    """Print text to stdout and optionally copy it to the clipboard."""
+    print(text)
+    if copy:
+        if copy_to_clipboard(text):
+            if not quiet:
+                info(c("%s copied to clipboard" % sym("ok"), "green"))
+        else:
+            info(c("could not copy to clipboard on this system", "yellow"))
+
+
+# ----------------------------------------------------------------- config
+
+def config_dir() -> Path:
+    if os.name == "nt":
+        base = os.environ.get("APPDATA") or str(Path.home() / "AppData" / "Roaming")
+    else:
+        base = os.environ.get("XDG_CONFIG_HOME") or str(Path.home() / ".config")
+    return Path(base) / "dkt"
+
+
+def load_json_file(path: Path, default):
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        return default
+
+
+def save_json_file(path: Path, data) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, indent=2, ensure_ascii=False, sort_keys=True), encoding="utf-8")
+
+
+def load_config() -> dict:
+    return load_json_file(config_dir() / "config.json", {})
+
+
+def get_setting(key: str, default=None):
+    """Environment variable DKT_<KEY> wins, then ~/.config/dkt/config.json."""
+    env = os.environ.get("DKT_" + key.upper())
+    if env:
+        return env
+    return load_config().get(key, default)
+
+
+# ----------------------------------------------------------------- misc
+
+def tool_version(cmd: Sequence[str]) -> Optional[str]:
+    """First line of `cmd --version`, or None if the tool is missing."""
+    if not shutil.which(cmd[0]):
+        return None
+    try:
+        r = subprocess.run(list(cmd), stdout=subprocess.PIPE, stderr=subprocess.STDOUT,
+                           stdin=subprocess.DEVNULL, timeout=10)
+        out = decode_output(r.stdout).strip().splitlines()
+        return out[0].strip() if out else "installed"
+    except Exception:
+        return "installed"
+
+
+def walk_files(folder: Path, skip_dirs=None):
+    """Yield files under folder, skipping heavy/vcs directories (no gitignore needed)."""
+    skip = IGNORE_DIRS if skip_dirs is None else skip_dirs
+    for root, dirs, files in os.walk(str(folder)):
+        dirs[:] = [d for d in dirs if d not in skip and not d.endswith(".egg-info")]
+        for f in files:
+            yield Path(root, f)