dktcli 1.0.0__py3-none-any.whl

devkittools/tools/cron.py

@@ -0,0 +1,152 @@
+"""dkt cron - explain a cron expression and show its next run times."""
+from __future__ import annotations
+
+import argparse
+from datetime import datetime, timedelta
+
+from ..utils import DktError, c, kv
+
+META = ("Data & Text", "cron", "", "explain cron expressions, preview next runs")
+
+EPILOG = """\
+examples:
+  dkt cron "*/15 * * * *"
+  dkt cron "0 9 * * mon-fri" -n 10
+  dkt cron "30 2 1 * *"
+  dkt cron @daily
+"""
+
+MONTHS = ["jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec"]
+DAYS = ["sun", "mon", "tue", "wed", "thu", "fri", "sat"]
+ALIASES = {"@yearly": "0 0 1 1 *", "@annually": "0 0 1 1 *", "@monthly": "0 0 1 * *",
+           "@weekly": "0 0 * * 0", "@daily": "0 0 * * *", "@midnight": "0 0 * * *", "@hourly": "0 * * * *"}
+
+
+def _val(tok: str, names, lo: int) -> int:
+    t = tok.lower()
+    if names and t in names:
+        return names.index(t) + (lo if names is MONTHS else 0)
+    if not t.isdigit():
+        raise DktError("Bad cron value '%s'" % tok)
+    return int(t)
+
+
+def parse_field(field: str, lo: int, hi: int, names=None):
+    out = set()
+    for part in field.split(","):
+        step = 1
+        if "/" in part:
+            part, st = part.split("/", 1)
+            if not st.isdigit() or int(st) < 1:
+                raise DktError("Bad step '/%s'" % st)
+            step = int(st)
+        if part in ("*", "?"):
+            a, b = lo, hi
+        elif "-" in part:
+            x, y = part.split("-", 1)
+            a, b = _val(x, names, lo), _val(y, names, lo)
+        else:
+            a = _val(part, names, lo)
+            b = hi if step > 1 else a
+        if a < lo or b > hi or a > b:
+            raise DktError("Value out of range (%d-%d): %s" % (lo, hi, part))
+        for v in range(a, b + 1, step):
+            out.add(0 if (hi == 7 and v == 7) else v)
+    return out
+
+
+def parse(expr: str):
+    expr = ALIASES.get(expr.strip().lower(), expr.strip())
+    f = expr.split()
+    if len(f) != 5:
+        raise DktError("Expected 5 fields (min hour day month weekday), got %d." % len(f))
+    return {
+        "min": parse_field(f[0], 0, 59), "hour": parse_field(f[1], 0, 23),
+        "dom": parse_field(f[2], 1, 31), "mon": parse_field(f[3], 1, 12, MONTHS),
+        "dow": parse_field(f[4], 0, 7, DAYS), "raw": f,
+    }
+
+
+def next_runs(spec, n: int, start: datetime):
+    runs = []
+    day = start.replace(hour=0, minute=0, second=0, microsecond=0)
+    dom_star, dow_star = spec["raw"][2] in ("*", "?"), spec["raw"][4] in ("*", "?")
+    for _ in range(366 * 8):
+        if day.month in spec["mon"]:
+            dom_ok = day.day in spec["dom"]
+            dow_ok = ((day.weekday() + 1) % 7) in spec["dow"]
+            if dom_star and dow_star:
+                day_ok = True
+            elif dom_star:
+                day_ok = dow_ok
+            elif dow_star:
+                day_ok = dom_ok
+            else:
+                day_ok = dom_ok or dow_ok
+            if day_ok:
+                for h in sorted(spec["hour"]):
+                    for m in sorted(spec["min"]):
+                        t = day.replace(hour=h, minute=m)
+                        if t > start:
+                            runs.append(t)
+                            if len(runs) >= n:
+                                return runs
+        day += timedelta(days=1)
+    return runs
+
+
+def _list(vals, names=None):
+    vals = sorted(vals)
+    return ", ".join(names[v] if names else str(v) for v in vals)
+
+
+def explain(spec) -> str:
+    mi, ho, dm, mo, dw = spec["raw"]
+    parts = []
+    if mi == "*" and ho == "*":
+        parts.append("every minute")
+    elif mi.startswith("*/") and ho == "*":
+        parts.append("every %s minutes" % mi[2:])
+    elif ho == "*" and mi.isdigit():
+        parts.append("at minute %s of every hour" % mi)
+    elif mi.isdigit() and ho.isdigit():
+        parts.append("at %02d:%02d" % (int(ho), int(mi)))
+    else:
+        parts.append("at minute(s) %s past hour(s) %s" % (_list(spec["min"]), _list(spec["hour"])))
+    if dm not in ("*", "?"):
+        parts.append("on day-of-month %s" % _list(spec["dom"]))
+    if mo != "*":
+        parts.append("in %s" % _list(spec["mon"], [""] + [m.title() for m in MONTHS]))
+    if dw not in ("*", "?"):
+        parts.append("on %s" % _list(spec["dow"], [d.title() for d in DAYS]))
+    return ", ".join(parts)
+
+
+def run(args) -> int:
+    expr = " ".join(args.expr)
+    spec = parse(expr)
+    print()
+    print("  " + c(explain(spec), "bold bcyan"))
+    print()
+    rows = []
+    now = datetime.now()
+    for t in next_runs(spec, args.n, now):
+        d = t - now
+        mins = int(d.total_seconds() // 60)
+        rel = "in %dd %dh" % (mins // 1440, (mins % 1440) // 60) if mins >= 1440 else \
+              "in %dh %dm" % (mins // 60, mins % 60) if mins >= 60 else "in %dm" % mins
+        rows.append((t.strftime("%a %Y-%m-%d %H:%M"), c(rel, "gray")))
+    if not rows:
+        raise DktError("That expression never runs (check day/month combination).")
+    kv(rows, key_color="bold")
+    print()
+    return 0
+
+
+def register(sub, common) -> None:
+    p = sub.add_parser("cron", parents=[common], help=META[3],
+                       description="Explain a crontab expression and list upcoming runs.",
+                       epilog=EPILOG, formatter_class=argparse.RawDescriptionHelpFormatter)
+    p.add_argument("expr", nargs="+", help='e.g. "*/5 * * * *" or @daily')
+    p.add_argument("-n", type=int, default=5, help="how many upcoming runs (default 5)")
+    p.set_defaults(func=run)

devkittools/tools/doctor.py

@@ -0,0 +1,74 @@
+"""dkt doctor (dr) - system info and a check of the dev tools installed on this machine."""
+from __future__ import annotations
+
+import argparse
+import os
+import platform
+import shutil
+import sys
+
+from ..utils import box, c, human_size, kv, sym, table, tool_version, Spinner, heading
+
+META = ("System", "doctor", "dr", "system info + which dev tools are installed (git, node, docker...)")
+
+EPILOG = """\
+examples:
+  dkt dr              full report
+  dkt dr --tools      only the tool checklist
+"""
+
+TOOLS = [
+    ("Python", ["python", "--version"], "python"), ("pip", ["pip", "--version"], "pip"),
+    ("Git", ["git", "--version"], "git"), ("GitHub CLI", ["gh", "--version"], "gh"),
+    ("Node.js", ["node", "--version"], "node"), ("npm", ["npm", "--version"], "npm"),
+    ("pnpm", ["pnpm", "--version"], "pnpm"), ("Yarn", ["yarn", "--version"], "yarn"),
+    ("Bun", ["bun", "--version"], "bun"), ("Deno", ["deno", "--version"], "deno"),
+    ("Docker", ["docker", "--version"], "docker"), ("Go", ["go", "version"], "go"),
+    ("Rust (cargo)", ["cargo", "--version"], "cargo"), ("Java", ["java", "-version"], "java"),
+    (".NET", ["dotnet", "--version"], "dotnet"), ("PHP", ["php", "--version"], "php"),
+    ("Ruby", ["ruby", "--version"], "ruby"), ("CMake", ["cmake", "--version"], "cmake"),
+    ("Make", ["make", "--version"], "make"), ("curl", ["curl", "--version"], "curl"),
+    ("SSH", ["ssh", "-V"], "ssh"), ("VS Code", ["code", "--version"], "code"),
+    ("Ollama", ["ollama", "--version"], "ollama"),
+]
+
+
+def run(args) -> int:
+    from .. import __version__
+    if not args.tools:
+        try:
+            disk = shutil.disk_usage(os.getcwd())
+            disk_s = "%s free of %s" % (human_size(disk.free), human_size(disk.total))
+        except Exception:
+            disk_s = "?"
+        box("system", [
+            "%s  %s %s" % (c("os      ", "gray"), platform.system(), platform.release()),
+            "%s  %s" % (c("machine ", "gray"), platform.machine()),
+            "%s  %s cores" % (c("cpu     ", "gray"), os.cpu_count()),
+            "%s  %s" % (c("disk    ", "gray"), disk_s),
+            "%s  %s (%s)" % (c("python  ", "gray"), platform.python_version(), sys.executable),
+            "%s  %s" % (c("shell   ", "gray"), os.environ.get("SHELL") or os.environ.get("COMSPEC") or "?"),
+            "%s  %s" % (c("dkt     ", "gray"), __version__),
+        ])
+        print()
+    rows = []
+    found = 0
+    with Spinner("checking tools"):
+        for label, cmd, exe in TOOLS:
+            ver = tool_version(cmd) if shutil.which(exe) else None
+            if ver:
+                found += 1
+                rows.append((c(sym("ok"), "bgreen"), label, ver[:60]))
+            else:
+                rows.append((c(sym("fail"), "gray"), c(label, "gray"), c("not found", "gray")))
+    table(["", "TOOL", "VERSION"], rows)
+    print("\n  %d of %d tools found\n" % (found, len(TOOLS)))
+    return 0
+
+
+def register(sub, common) -> None:
+    p = sub.add_parser("doctor", aliases=["dr"], parents=[common], help=META[3],
+                       description="Inspect this machine's developer setup.", epilog=EPILOG,
+                       formatter_class=argparse.RawDescriptionHelpFormatter)
+    p.add_argument("--tools", action="store_true", help="only the tool checklist")
+    p.set_defaults(func=run)

devkittools/tools/du.py

@@ -0,0 +1,72 @@
+"""dkt du - what is eating my disk? Biggest folders and files with bars."""
+from __future__ import annotations
+
+import argparse
+import os
+from pathlib import Path
+
+from ..utils import Spinner, bar, c, human_size, resolve_folder, sym
+
+META = ("Project & Code", "du", "", "biggest folders & files with bars (full disk, no gitignore)")
+
+EPILOG = """\
+examples:
+  dkt du                  biggest items inside the current folder
+  dkt du ~/Downloads -n 20
+  dkt du --files          largest individual files anywhere below
+"""
+
+
+def run(args) -> int:
+    root = resolve_folder(args.folder)
+    sizes = {}
+    big_files = []
+    with Spinner("measuring %s" % root.name):
+        try:
+            entries = list(os.scandir(str(root)))
+        except PermissionError:
+            entries = []
+        for e in entries:
+            total = 0
+            try:
+                if e.is_file(follow_symlinks=False):
+                    total = e.stat(follow_symlinks=False).st_size
+                    big_files.append((total, Path(e.path)))
+                elif e.is_dir(follow_symlinks=False):
+                    for cur, _, files in os.walk(e.path):
+                        for f in files:
+                            try:
+                                s = os.lstat(os.path.join(cur, f)).st_size
+                            except OSError:
+                                continue
+                            total += s
+                            if args.files:
+                                big_files.append((s, Path(cur, f)))
+            except OSError:
+                continue
+            sizes[e.name + ("/" if e.is_dir(follow_symlinks=False) else "")] = total
+    if args.files:
+        rows = sorted(big_files, key=lambda x: -x[0])[:args.n]
+        mx = rows[0][0] if rows else 1
+        for s, p in rows:
+            print("  %9s  %s  %s" % (human_size(s), c(bar(s, mx, 16), "bcyan"), p.relative_to(root)))
+        return 0
+    items = sorted(sizes.items(), key=lambda kv: -kv[1])[:args.n]
+    total = sum(sizes.values())
+    mx = items[0][1] if items else 1
+    for name, s in items:
+        pct = (100.0 * s / total) if total else 0
+        print("  %9s  %s  %4.1f%%  %s" % (human_size(s), c(bar(s, mx, 20), "bcyan"), pct,
+                                         c(name, "bold bblue") if name.endswith("/") else name))
+    print(c("\n  total %s" % human_size(total), "gray"))
+    return 0
+
+
+def register(sub, common) -> None:
+    p = sub.add_parser("du", parents=[common], help=META[3],
+                       description="Disk usage overview.", epilog=EPILOG,
+                       formatter_class=argparse.RawDescriptionHelpFormatter)
+    p.add_argument("folder", nargs="?")
+    p.add_argument("-n", type=int, default=15, help="rows to show (default 15)")
+    p.add_argument("--files", action="store_true", help="list the biggest individual files")
+    p.set_defaults(func=run)

devkittools/tools/enc.py

@@ -0,0 +1,131 @@
+"""dkt enc (e) and dkt jwt - encode/decode base64, url, hex, html; decode JWTs."""
+from __future__ import annotations
+
+import argparse
+import base64
+import binascii
+import html
+import json
+import time
+import urllib.parse
+from datetime import datetime, timezone
+
+from ..utils import DktError, c, info, output_result, read_input, kv, warn, ok
+
+META = ("Generate & Convert", "enc", "e", "base64 / url / hex / html encode & decode, plus JWT decoder")
+
+EPILOG = """\
+examples:
+  dkt enc b64 "hello"            aGVsbG8=
+  dkt enc b64 aGVsbG8= -d        hello
+  dkt enc url "a b&c=d"          url-encode
+  dkt enc hex "hi" --copy
+  dkt jwt eyJhbGciOi...          decode a JWT (signature is NOT verified)
+"""
+
+
+def _b64d(s: str, urlsafe: bool) -> bytes:
+    s = "".join(s.split())
+    s += "=" * (-len(s) % 4)
+    return base64.urlsafe_b64decode(s) if urlsafe else base64.b64decode(s)
+
+
+def convert(kind: str, text: str, decode: bool) -> str:
+    try:
+        if kind in ("b64", "b64url"):
+            urlsafe = kind == "b64url"
+            if decode:
+                return _b64d(text, urlsafe).decode("utf-8", errors="replace")
+            raw = text.encode("utf-8")
+            return (base64.urlsafe_b64encode(raw) if urlsafe else base64.b64encode(raw)).decode()
+        if kind == "url":
+            return urllib.parse.unquote_plus(text) if decode else urllib.parse.quote(text, safe="")
+        if kind == "hex":
+            if decode:
+                return bytes.fromhex("".join(text.split())).decode("utf-8", errors="replace")
+            return text.encode("utf-8").hex()
+        if kind == "html":
+            return html.unescape(text) if decode else html.escape(text)
+    except (binascii.Error, ValueError) as e:
+        raise DktError("Could not decode as %s: %s" % (kind, e))
+    raise DktError("Unknown kind %s" % kind)
+
+
+def run_enc(args) -> int:
+    text = read_input(args.text, args.file, args.paste, "text")
+    if args.file is None and args.text is None:
+        text = text.rstrip("\n")
+    output_result(convert(args.kind, text, args.decode), copy=args.copy)
+    return 0
+
+
+def _ts(label: str, value) -> str:
+    try:
+        dt = datetime.fromtimestamp(int(value), tz=timezone.utc)
+        delta = int(value) - int(time.time())
+        rel = ("in %s" % _dur(delta)) if delta > 0 else ("%s ago" % _dur(-delta))
+        return "%s  %s  %s" % (value, dt.strftime("%Y-%m-%d %H:%M:%S UTC"), c("(%s)" % rel, "gray"))
+    except Exception:
+        return str(value)
+
+
+def _dur(s: int) -> str:
+    for unit, n in (("d", 86400), ("h", 3600), ("m", 60)):
+        if s >= n:
+            return "%d%s" % (s // n, unit)
+    return "%ds" % s
+
+
+def run_jwt(args) -> int:
+    token = read_input(args.token, None, args.paste, "token").strip()
+    if token.lower().startswith("bearer "):
+        token = token[7:].strip()
+    parts = token.split(".")
+    if len(parts) < 2:
+        raise DktError("That doesn't look like a JWT (expected header.payload.signature).")
+    try:
+        header = json.loads(_b64d(parts[0], True))
+        payload = json.loads(_b64d(parts[1], True))
+    except Exception:
+        raise DktError("Could not decode the JWT parts - is the token complete?")
+    from .jsontool import colorize
+    print(c("HEADER", "bold bcyan"))
+    print(colorize(json.dumps(header, indent=2)))
+    print(c("PAYLOAD", "bold bmagenta"))
+    print(colorize(json.dumps(payload, indent=2)))
+    rows = []
+    for k, label in (("iat", "issued"), ("nbf", "not before"), ("exp", "expires")):
+        if k in payload:
+            rows.append((label, _ts(k, payload[k])))
+    if rows:
+        print()
+        kv(rows)
+    if "exp" in payload:
+        try:
+            if int(payload["exp"]) < time.time():
+                warn("token is EXPIRED")
+            else:
+                ok("token not expired")
+        except Exception:
+            pass
+    info(c("note: signature is not verified", "gray"))
+    return 0
+
+
+def register(sub, common) -> None:
+    p = sub.add_parser("enc", aliases=["e"], parents=[common], help=META[3],
+                       description="Encode or decode text.", epilog=EPILOG,
+                       formatter_class=argparse.RawDescriptionHelpFormatter)
+    p.add_argument("kind", choices=["b64", "b64url", "url", "hex", "html"])
+    p.add_argument("text", nargs="?", help="text (or pipe stdin)")
+    p.add_argument("-d", "--decode", action="store_true", help="decode instead of encode")
+    p.add_argument("-f", "--file", metavar="FILE")
+    p.add_argument("--paste", action="store_true", help="read from clipboard")
+    p.add_argument("--copy", action="store_true")
+    p.set_defaults(func=run_enc)
+
+    j = sub.add_parser("jwt", parents=[common], help="decode a JSON Web Token",
+                       description="Decode a JWT and show whether it has expired.")
+    j.add_argument("token", nargs="?")
+    j.add_argument("--paste", action="store_true", help="read token from clipboard")
+    j.set_defaults(func=run_jwt)

devkittools/tools/envtool.py

@@ -0,0 +1,141 @@
+"""dkt env - inspect environment variables, PATH and compare .env files."""
+from __future__ import annotations
+
+import argparse
+import os
+import re
+from pathlib import Path
+
+from ..utils import DktError, c, fail, ok, warn, table, sym, resolve_folder, kv, heading
+
+META = ("Project & Code", "env", "", "env vars, PATH doctor, .env vs .env.example check")
+
+EPILOG = """\
+examples:
+  dkt env                     list variables (secrets masked)
+  dkt env HOME                one variable
+  dkt env -g java             variables matching 'java'
+  dkt env path                PATH entries, flagging missing / duplicate ones
+  dkt env check               compare .env with .env.example in this folder
+  dkt env show --reveal       don't mask secret-looking values
+"""
+
+SECRET_RE = re.compile(r"(key|secret|token|passw|pwd|auth|credential|private)", re.I)
+
+
+def mask(name: str, value: str, reveal: bool) -> str:
+    if reveal or not SECRET_RE.search(name) or not value:
+        return value
+    return value[:2] + "*" * max(4, min(len(value) - 2, 12)) if len(value) > 4 else "****"
+
+
+def parse_env_file(path: Path):
+    data = {}
+    for raw in path.read_text(encoding="utf-8", errors="replace").splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        if line.startswith("export "):
+            line = line[7:]
+        if "=" not in line:
+            continue
+        k, v = line.split("=", 1)
+        data[k.strip()] = v.strip().strip("'\"")
+    return data
+
+
+def cmd_list(args) -> int:
+    items = sorted(os.environ.items(), key=lambda kv_: kv_[0].lower())
+    if args.name:
+        want = args.name
+        hit = [(k, v) for k, v in items if k.lower() == want.lower()]
+        if not hit:
+            raise DktError("%s is not set." % want)
+        print(hit[0][1])
+        return 0
+    if args.grep:
+        g = args.grep.lower()
+        items = [(k, v) for k, v in items if g in k.lower() or g in v.lower()]
+    rows = [(c(k, "bcyan"), mask(k, v, args.reveal)[:90]) for k, v in items]
+    if not rows:
+        print("  no matches")
+        return 0
+    table(["NAME", "VALUE"], rows)
+    print("\n  %d variables" % len(rows))
+    return 0
+
+
+def cmd_path(args) -> int:
+    sep = ";" if os.name == "nt" else ":"
+    entries = [e for e in os.environ.get("PATH", "").split(sep) if e]
+    seen = set()
+    rows = []
+    bad = 0
+    for i, e in enumerate(entries, 1):
+        norm = os.path.normcase(os.path.normpath(os.path.expandvars(e)))
+        status = c(sym("ok"), "bgreen")
+        note = ""
+        if not os.path.isdir(os.path.expandvars(e)):
+            status, note = c(sym("fail"), "bred"), c("missing", "red")
+            bad += 1
+        elif norm in seen:
+            status, note = c(sym("warn"), "byellow"), c("duplicate", "yellow")
+            bad += 1
+        seen.add(norm)
+        rows.append((i, status, e, note))
+    table(["#", "", "PATH ENTRY", ""], rows)
+    print()
+    (warn if bad else ok)("%d entries, %d problem%s" % (len(entries), bad, "" if bad == 1 else "s"))
+    return 0
+
+
+def cmd_check(args) -> int:
+    folder = resolve_folder(args.folder)
+    env_file = folder / args.env_file
+    example = None
+    for name in (args.example, ".env.example", ".env.sample", ".env.template", "example.env"):
+        if name and (folder / name).is_file():
+            example = folder / name
+            break
+    if not env_file.is_file():
+        raise DktError("No %s in %s" % (args.env_file, folder))
+    if not example:
+        raise DktError("No .env.example / .env.sample found to compare against.")
+    have, want = parse_env_file(env_file), parse_env_file(example)
+    missing = sorted(set(want) - set(have))
+    extra = sorted(set(have) - set(want))
+    empty = sorted(k for k, v in have.items() if k in want and v == "")
+    print("  comparing %s  vs  %s" % (c(env_file.name, "bold"), c(example.name, "bold")))
+    print()
+    for k in missing:
+        fail("missing in %s: %s" % (env_file.name, c(k, "bold")))
+    for k in empty:
+        warn("empty value: %s" % c(k, "bold"))
+    for k in extra:
+        print("  %s not in %s: %s" % (c(sym("dot"), "gray"), example.name, k))
+    if not (missing or empty):
+        ok("all %d expected variables are set" % len(want))
+    return 1 if missing else 0
+
+
+def register(sub, common) -> None:
+    p = sub.add_parser("env", parents=[common], help=META[3],
+                       description="Inspect environment variables and .env files.",
+                       epilog=EPILOG, formatter_class=argparse.RawDescriptionHelpFormatter)
+    p.add_argument("name", nargs="?", help="variable to print, or: path | check | show")
+    p.add_argument("-g", "--grep", metavar="TEXT", help="filter by name/value")
+    p.add_argument("--reveal", action="store_true", help="don't mask secret-looking values")
+    p.add_argument("-f", "--folder", metavar="PATH", help="project folder for 'check'")
+    p.add_argument("--env-file", default=".env", help="file to check (default .env)")
+    p.add_argument("--example", help="template file (default: auto-detect .env.example)")
+    p.set_defaults(func=_dispatch)
+
+
+def _dispatch(args) -> int:
+    if args.name == "path":
+        return cmd_path(args)
+    if args.name == "check":
+        return cmd_check(args)
+    if args.name == "show":
+        args.name = None
+    return cmd_list(args)