dktcli 1.0.0__py3-none-any.whl

devkittools/__init__.py

@@ -0,0 +1,3 @@
+"""devkittools - a suite of small developer CLI tools (command: dkt)."""
+
+__version__ = "1.0.0"

devkittools/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

devkittools/cli.py

@@ -0,0 +1,179 @@
+"""Entry point for the `dkt` command."""
+from __future__ import annotations
+
+import argparse
+import difflib
+import re
+import shlex
+import sys
+from typing import List, Optional
+
+from . import __version__
+from .tools import (bench, changeloggen, clean, colortool, commitwriter, contextpacker, cron, doctor, du, enc,
+                    envtool, findtool, gen, gx, hashtool, httptool, ignore, initproj, jsontool, net, portkiller,
+                    regextool, repostats, secrets_scan, serve, snip, system, timetool, todo, tree, watch)
+from .utils import DktError, banner, c, is_interactive, ask, setup_console, sym, term_width
+
+VERSION_STR = "devkittools %s" % __version__
+
+# Order here = order in the help screen.
+MODULES = [
+    portkiller, serve, httptool, net,
+    repostats, tree, findtool, todo, secrets_scan, clean, du, watch, bench, envtool, ignore, initproj,
+    gx, changeloggen,
+    contextpacker, commitwriter,
+    gen, enc, hashtool, timetool, colortool,
+    jsontool, regextool, cron, snip,
+    doctor,
+]
+CATEGORY_ORDER = ["Servers & Network", "Project & Code", "Git", "AI Helpers", "Generate & Convert",
+                  "Data & Text", "System"]
+EXTRA = [  # (category, name, alias, summary) for commands without a META of their own
+    ("Generate & Convert", "jwt", "", "decode JSON Web Tokens"),
+    ("Project & Code", "license", "lic", "write a LICENSE file"),
+    ("dkt itself", "update", "", "upgrade dkt to the newest version"),
+    ("dkt itself", "config", "", "view / change settings"),
+    ("dkt itself", "completion", "", "shell tab-completion script"),
+    ("dkt itself", "menu", "", "interactive launcher"),
+    ("dkt itself", "about", "", "logo, version and tips"),
+]
+CATEGORY_ORDER.append("dkt itself")
+
+
+def all_tools():
+    rows = [m.META for m in MODULES] + EXTRA
+    return rows
+
+
+def grouped_help() -> str:
+    lines = []
+    cats = {}
+    for cat, name, alias, summary in all_tools():
+        cats.setdefault(cat, []).append((name, alias, summary))
+    for cat in CATEGORY_ORDER:
+        items = cats.get(cat)
+        if not items:
+            continue
+        lines.append("")
+        lines.append("  " + c(cat, "bold bmagenta"))
+        for name, alias, summary in items:
+            if len(name) > 12 and alias:
+                name, alias = alias, name
+            short = ("(%s)" % alias) if alias else ""
+            lines.append("    %s %s  %s" % (c(name.ljust(10), "bold bcyan"), c(short.ljust(6), "gray"), summary))
+    return "\n".join(lines)
+
+
+def print_overview() -> None:
+    banner()
+    print(grouped_help())
+    print()
+    print("  " + c("usage:", "bold") + " dkt <tool> [options]     " + c("dkt <tool> -h for examples", "gray"))
+    print("  " + c("tip:", "bold") + "   dkt menu for an interactive launcher, dkt completion for tab-complete")
+    print()
+
+
+class OverviewAction(argparse.Action):
+    def __init__(self, option_strings, dest, **kw):
+        super().__init__(option_strings, dest, nargs=0, **kw)
+
+    def __call__(self, parser, namespace, values, option_string=None):
+        print_overview()
+        parser.exit(0)
+
+
+class DktParser(argparse.ArgumentParser):
+    tool_names: List[str] = []
+
+    def error(self, message):
+        m = re.search(r"invalid choice: '([^']*)'", message)
+        if m and self.prog == "dkt":
+            bad = m.group(1)
+            guess = difflib.get_close_matches(bad, self.tool_names, n=3, cutoff=0.5)
+            sys.stderr.write("%s unknown tool '%s'\n" % (c("error:", "red"), bad))
+            if guess:
+                sys.stderr.write("  did you mean: %s ?\n" % ", ".join(c(g, "bold bcyan") for g in guess))
+            sys.stderr.write("  run 'dkt' to see all tools\n")
+            self.exit(2)
+        super().error(message)
+
+
+def build_parser():
+    parser = DktParser(prog="dkt", description="devkittools - the developer's swiss army knife.",
+                       add_help=False, formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("-h", "--help", action=OverviewAction, help="show all tools")
+    parser.add_argument("-v", "-V", "--version", action="version", version=VERSION_STR, help="show version")
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("-v", "-V", "--version", action="version", version=VERSION_STR, help="show version and exit")
+    sub = parser.add_subparsers(dest="command", metavar="<tool>", title="tools")
+    for m in MODULES:
+        m.register(sub, common)
+    system.register(sub, common)
+    menu = sub.add_parser("menu", aliases=["m"], parents=[common], help="interactive launcher")
+    menu.set_defaults(func=lambda a: run_menu())
+    DktParser.tool_names = sorted(sub.choices)
+    return parser
+
+
+def run_menu() -> int:
+    if not is_interactive():
+        print_overview()
+        return 0
+    banner()
+    tools = []
+    cats = {}
+    for cat, name, alias, summary in all_tools():
+        if name in ("menu",):
+            continue
+        cats.setdefault(cat, []).append((name, alias, summary))
+    n = 0
+    for cat in CATEGORY_ORDER:
+        if cat not in cats:
+            continue
+        print("  " + c(cat, "bold bmagenta"))
+        for name, alias, summary in cats[cat]:
+            n += 1
+            tools.append(name)
+            print("   %s %s  %s" % (c(str(n).rjust(2), "gray"), c(name.ljust(10), "bold bcyan"), summary))
+        print()
+    while True:
+        pick = ask("pick a tool by number or name (q to quit)")
+        if pick.lower() in ("", "q", "quit", "exit"):
+            return 0
+        name = tools[int(pick) - 1] if pick.isdigit() and 0 < int(pick) <= len(tools) else pick
+        print()
+        main([name, "--help"] if True else [])
+        line = ask("arguments (blank = run with none, 'b' = back)")
+        if line.lower() == "b":
+            continue
+        try:
+            argv = [name] + shlex.split(line)
+        except ValueError as e:
+            print(c("bad quoting: %s" % e, "red"))
+            continue
+        print()
+        main(argv)
+        print()
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    setup_console()
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if not getattr(args, "func", None):
+        print_overview()
+        return 0
+    try:
+        return int(args.func(args) or 0)
+    except DktError as e:
+        print(c("error:", "red"), e, file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        print(file=sys.stderr)
+        return 130
+    except BrokenPipeError:
+        return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

devkittools/tools/__init__.py

@@ -0,0 +1 @@
+"""Individual dkt tools. Each module exposes register(subparsers, common) and run(args)."""

devkittools/tools/bench.py

@@ -0,0 +1,73 @@
+"""dkt bench (bn) - time a command over several runs."""
+from __future__ import annotations
+
+import argparse
+import statistics
+import subprocess
+import time
+
+from ..utils import DktError, Spinner, bar, c, kv
+
+META = ("Project & Code", "bench", "bn", "benchmark any command: min/mean/max over N runs")
+
+EPILOG = """\
+examples:
+  dkt bn "python script.py"
+  dkt bn "node a.js" "node b.js" -n 20      compare two commands
+  dkt bn "make build" --warmup 2 --runs 5
+"""
+
+
+def fmt(s: float) -> str:
+    return "%.0f ms" % (s * 1000) if s < 1 else "%.2f s" % s
+
+
+def time_cmd(cmd: str, runs: int, warmup: int):
+    times = []
+    fails = 0
+    for i in range(warmup + runs):
+        t0 = time.perf_counter()
+        rc = subprocess.call(cmd, shell=True, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+        dt = time.perf_counter() - t0
+        if i >= warmup:
+            times.append(dt)
+            fails += rc != 0
+    return times, fails
+
+
+def run(args) -> int:
+    if not args.commands:
+        raise DktError('Give at least one command, e.g. dkt bn "python script.py"')
+    results = []
+    for cmd in args.commands:
+        with Spinner("benchmarking: %s" % cmd):
+            times, fails = time_cmd(cmd, args.runs, args.warmup)
+        results.append((cmd, times, fails))
+    best = min(statistics.mean(t) for _, t, _ in results)
+    for cmd, times, fails in results:
+        mean = statistics.mean(times)
+        print("\n  " + c(cmd, "bold bcyan"))
+        rows = [("mean", c(fmt(mean), "bold") + (" " + c("± " + fmt(statistics.stdev(times)), "gray") if len(times) > 1 else "")),
+                ("range", "%s … %s" % (fmt(min(times)), fmt(max(times)))),
+                ("runs", "%d%s" % (len(times), c("  (%d failed)" % fails, "red") if fails else ""))]
+        if len(results) > 1:
+            rows.append(("vs best", "%.2fx" % (mean / best) if mean > best else c("fastest", "bgreen")))
+        kv(rows)
+    if len(results) > 1:
+        print()
+        mx = max(statistics.mean(t) for _, t, _ in results)
+        for cmd, times, _ in results:
+            m = statistics.mean(times)
+            print("  %s %s  %s" % (c(bar(m, mx, 24), "bmagenta"), fmt(m).rjust(8), cmd))
+    print()
+    return 0
+
+
+def register(sub, common) -> None:
+    p = sub.add_parser("bench", aliases=["bn"], parents=[common], help=META[3],
+                       description="Benchmark shell commands.", epilog=EPILOG,
+                       formatter_class=argparse.RawDescriptionHelpFormatter)
+    p.add_argument("commands", nargs="*", metavar="CMD")
+    p.add_argument("-n", "--runs", type=int, default=10)
+    p.add_argument("--warmup", type=int, default=1)
+    p.set_defaults(func=run)

devkittools/tools/changeloggen.py

@@ -0,0 +1,181 @@
+"""dkt changeloggen (clg) - turn git commits into a CHANGELOG.md."""
+from __future__ import annotations
+
+import argparse
+import datetime
+import re
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+from ..utils import DktError, c, git, info, require_git_repo, resolve_folder
+
+EPILOG = """\
+examples:
+  dkt clg                          CHANGELOG.md for the current folder
+  dkt clg --folder "C:\\code\\app"  for another project
+  dkt clg --stdout                 print instead of writing a file
+  dkt clg --since v1.2.0           only changes after a tag/commit
+  dkt clg -o docs/HISTORY.md --authors
+"""
+
+CATEGORIES = [
+    ("feat", "Features", "✨"),
+    ("fix", "Bug Fixes", "🐛"),
+    ("perf", "Performance", "⚡"),
+    ("refactor", "Refactoring", "♻️"),
+    ("docs", "Documentation", "📝"),
+    ("style", "Style", "💄"),
+    ("test", "Tests", "✅"),
+    ("build", "Build", "📦"),
+    ("ci", "CI", "🤖"),
+    ("chore", "Chores", "🧹"),
+    ("revert", "Reverts", "⏪"),
+    ("other", "Other Changes", "🔧"),
+]
+KNOWN_TYPES = {t for t, _, _ in CATEGORIES if t != "other"}
+CONV_RE = re.compile(r"^(\w+)(?:\(([^)]+)\))?(!)?:\s*(.+)$")
+
+
+def parse_commit(subject: str, body: str = "") -> dict:
+    m = CONV_RE.match(subject.strip())
+    if m and m.group(1).lower() in KNOWN_TYPES:
+        ctype, scope, bang, desc = m.group(1).lower(), m.group(2), m.group(3), m.group(4)
+    else:
+        ctype, scope, bang, desc = "other", None, None, subject.strip()
+    breaking = bool(bang) or "BREAKING CHANGE" in body
+    return {"type": ctype, "scope": scope, "desc": desc, "breaking": breaking}
+
+
+def remote_base_url(folder: Path) -> Optional[str]:
+    url = git(folder, "remote", "get-url", "origin", check=False).strip()
+    if not url:
+        return None
+    m = re.match(r"^git@([^:]+):(.+?)(?:\.git)?/?$", url)
+    if m:
+        return "https://%s/%s" % (m.group(1), m.group(2))
+    m = re.match(r"^ssh://(?:[^@/]+@)?([^/]+)/(.+?)(?:\.git)?/?$", url)
+    if m:
+        return "https://%s/%s" % (m.group(1), m.group(2))
+    if url.startswith("http"):
+        url = re.sub(r"//[^@/]+@", "//", url)
+        return re.sub(r"\.git/?$", "", url).rstrip("/")
+    return None
+
+
+def get_commits(folder: Path, rng: str) -> List[dict]:
+    fmt = "%H%x1f%h%x1f%s%x1f%an%x1f%b%x1e"
+    out = git(folder, "log", rng, "--no-merges", "--pretty=format:" + fmt)
+    commits = []
+    for rec in out.split("\x1e"):
+        rec = rec.strip("\r\n")
+        if not rec.strip():
+            continue
+        f = rec.split("\x1f")
+        if len(f) < 4:
+            continue
+        body = f[4] if len(f) > 4 else ""
+        item = parse_commit(f[2], body)
+        item.update({"hash": f[0].strip(), "short": f[1].strip(), "author": f[3].strip()})
+        commits.append(item)
+    return commits
+
+
+def get_tags(folder: Path) -> List[Tuple[str, str]]:
+    out = git(folder, "for-each-ref", "--sort=-creatordate",
+              "--format=%(refname:short)\t%(creatordate:short)", "refs/tags", check=False)
+    tags = []
+    for line in out.splitlines():
+        if "\t" in line:
+            name, date = line.split("\t", 1)
+            tags.append((name.strip(), date.strip()))
+    return tags
+
+
+def render_section(title: str, date: str, commits: List[dict], base: Optional[str],
+                   authors: bool, emoji: bool) -> str:
+    lines = ["## %s%s" % (title, " - %s" % date if date else ""), ""]
+    for ctype, label, icon in CATEGORIES:
+        group = [x for x in commits if x["type"] == ctype]
+        if not group:
+            continue
+        lines.append("### %s%s" % (icon + " " if emoji else "", label))
+        for x in group:
+            text = x["desc"]
+            if x["scope"]:
+                text = "**%s:** %s" % (x["scope"], text)
+            if x["breaking"]:
+                text = "**BREAKING** " + text
+            ref = "`%s`" % x["short"]
+            if base:
+                ref = "[%s](%s/commit/%s)" % (ref, base, x["hash"])
+            suffix = " (%s)" % ref
+            if authors:
+                suffix += " - %s" % x["author"]
+            lines.append("- " + text + suffix)
+        lines.append("")
+    return "\n".join(lines)
+
+
+def generate(folder: Path, since: Optional[str], authors: bool, emoji: bool) -> Tuple[str, int, int]:
+    base = remote_base_url(folder)
+    sections = []  # (title, date, commits)
+    today = datetime.date.today().isoformat()
+    if since:
+        commits = get_commits(folder, "%s..HEAD" % since)
+        sections.append(("Changes since %s" % since, today, commits))
+    else:
+        tags = get_tags(folder)
+        if not tags:
+            sections.append(("Unreleased", today, get_commits(folder, "HEAD")))
+        else:
+            sections.append(("Unreleased", today, get_commits(folder, "%s..HEAD" % tags[0][0])))
+            for i, (name, date) in enumerate(tags):
+                rng = name if i == len(tags) - 1 else "%s..%s" % (tags[i + 1][0], name)
+                sections.append((name, date, get_commits(folder, rng)))
+    total = sum(len(s[2]) for s in sections)
+    if total == 0:
+        raise DktError("No commits found to put in a changelog.")
+    parts = ["# Changelog", "",
+             "All notable changes to this project are listed here. "
+             "Generated by devkittools (`dkt clg`).", ""]
+    for title, date, commits in sections:
+        if commits:
+            parts.append(render_section(title, date, commits, base, authors, emoji))
+    return "\n".join(parts).rstrip() + "\n", total, len([s for s in sections if s[2]])
+
+
+def run(args: argparse.Namespace) -> int:
+    folder = resolve_folder(args.folder)
+    require_git_repo(folder)
+    if not git(folder, "rev-parse", "--verify", "HEAD", check=False).strip():
+        raise DktError("This repository has no commits yet.")
+    text, total, nsec = generate(folder, args.since, args.authors, not args.no_emoji)
+    if args.stdout:
+        print(text)
+        return 0
+    out = Path(args.output) if args.output else folder / "CHANGELOG.md"
+    if not out.is_absolute() and args.output:
+        out = Path.cwd() / out
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text(text, encoding="utf-8")
+    info("%s %s  (%d commits, %d section%s)" % (c("✔ Wrote", "green"), out, total, nsec, "" if nsec == 1 else "s"))
+    return 0
+
+
+def register(sub, common) -> None:
+    p = sub.add_parser(
+        "changeloggen", aliases=["clg"], parents=[common],
+        help="generate CHANGELOG.md from git commits",
+        description="Generate a clean, grouped CHANGELOG.md from your git history.\n"
+                    "Understands Conventional Commits (feat:, fix:, ...) and git tags.",
+        epilog=EPILOG, formatter_class=argparse.RawDescriptionHelpFormatter)
+    p.add_argument("-f", "--folder", metavar="PATH", help="project folder (default: current folder)")
+    p.add_argument("-o", "--output", metavar="FILE", help="output file (default: <folder>/CHANGELOG.md)")
+    p.add_argument("--since", metavar="REF", help="only include commits after this tag/commit")
+    p.add_argument("--stdout", action="store_true", help="print to the terminal instead of writing a file")
+    p.add_argument("--authors", action="store_true", help="show the author of each commit")
+    p.add_argument("--no-emoji", action="store_true", help="plain section headings")
+    p.set_defaults(func=run)
+
+
+META = ("Git", "changeloggen", "clg", "CHANGELOG.md from conventional commits & tags")

devkittools/tools/clean.py

@@ -0,0 +1,110 @@
+"""dkt clean (cl) - delete build caches and dependency folders to reclaim disk space."""
+from __future__ import annotations
+
+import argparse
+import os
+import shutil
+import stat
+from pathlib import Path
+
+from ..utils import c, confirm, human_size, ok, resolve_folder, table, sym, Spinner, warn
+
+META = ("Project & Code", "clean", "cl", "remove node_modules, __pycache__, caches (with sizes + confirm)")
+
+EPILOG = """\
+examples:
+  dkt cl                      preview what would be removed in this folder tree
+  dkt cl --yes                delete without asking
+  dkt cl --build              also dist/ build/ target/ out/
+  dkt cl --venv               also .venv/ venv/
+  dkt cl ~/projects --dry-run
+"""
+
+SAFE = {"node_modules", "__pycache__", ".pytest_cache", ".mypy_cache", ".ruff_cache", ".tox", ".next",
+        ".nuxt", ".parcel-cache", ".turbo", ".gradle", ".angular", ".svelte-kit", ".sass-cache", ".eslintcache",
+        "coverage", ".nyc_output", ".ipynb_checkpoints", ".cache"}
+BUILD = {"dist", "build", "out"}
+VENV = {".venv", "venv", "env"}
+
+
+def dir_size(path: Path) -> int:
+    total = 0
+    for root, _, files in os.walk(str(path)):
+        for f in files:
+            try:
+                total += os.lstat(os.path.join(root, f)).st_size
+            except OSError:
+                pass
+    return total
+
+
+def _rm_readonly(func, path, _exc):
+    try:
+        os.chmod(path, stat.S_IWRITE)
+        func(path)
+    except OSError:
+        pass
+
+
+def find_targets(root: Path, names):
+    found = []
+    for cur, dirs, _ in os.walk(str(root)):
+        keep = []
+        for d in dirs:
+            full = Path(cur, d)
+            if d == ".git":
+                continue
+            is_target = d in names or d.endswith(".egg-info")
+            if d == "target" and "target" in names and not ((Path(cur) / "Cargo.toml").exists() or (Path(cur) / "pom.xml").exists()):
+                is_target = False
+            if is_target and not full.is_symlink():
+                found.append(full)
+            elif not full.is_symlink():
+                keep.append(d)
+        dirs[:] = keep
+    return found
+
+
+def run(args) -> int:
+    root = resolve_folder(args.folder)
+    names = set(SAFE)
+    if args.build:
+        names |= BUILD | {"target"}
+    if args.venv:
+        names |= VENV
+    with Spinner("scanning %s" % root.name):
+        targets = find_targets(root, names)
+        sized = sorted(((dir_size(t), t) for t in targets), key=lambda x: -x[0])
+    if not sized:
+        ok("nothing to clean - %s is already tidy" % root.name)
+        return 0
+    rows = [(human_size(s), str(t.relative_to(root))) for s, t in sized[:40]]
+    table(["SIZE", "FOLDER"], rows)
+    if len(sized) > 40:
+        print(c("  ... and %d more" % (len(sized) - 40), "gray"))
+    total = sum(s for s, _ in sized)
+    print("\n  %s in %d folders" % (c(human_size(total), "bold bcyan"), len(sized)))
+    if args.dry_run:
+        return 0
+    if not args.yes and not confirm("Delete these %d folders?" % len(sized)):
+        print("  nothing deleted.")
+        return 0
+    removed = 0
+    with Spinner("deleting"):
+        for _, t in sized:
+            shutil.rmtree(str(t), onerror=_rm_readonly)
+            removed += 1
+    ok("freed %s (%d folders)" % (human_size(total), removed))
+    return 0
+
+
+def register(sub, common) -> None:
+    p = sub.add_parser("clean", aliases=["cl"], parents=[common], help=META[3],
+                       description="Find and remove regenerable folders. Never touches .git or source files.",
+                       epilog=EPILOG, formatter_class=argparse.RawDescriptionHelpFormatter)
+    p.add_argument("folder", nargs="?", help="root to scan (default: current folder)")
+    p.add_argument("--build", action="store_true", help="also dist/ build/ out/ target/")
+    p.add_argument("--venv", action="store_true", help="also .venv/ venv/ env/")
+    p.add_argument("--dry-run", action="store_true", help="only show what would go")
+    p.add_argument("-y", "--yes", action="store_true", help="don't ask for confirmation")
+    p.set_defaults(func=run)