dktcli 1.0.0__py3-none-any.whl

devkittools/tools/repostats.py

@@ -0,0 +1,197 @@
+"""dkt repostats (rs) - quick stats and health summary for a project."""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from collections import Counter
+from pathlib import Path
+from typing import Dict, List, Optional
+
+from ..utils import (bar, c, git, human_num, human_size, is_git_repo, list_project_files,
+                     resolve_folder)
+
+EPILOG = """\
+examples:
+  dkt rs                      stats for the current folder
+  dkt rs --folder "C:\\code\\app" --top 10
+  dkt rs --json               machine-readable output
+"""
+
+LANGS = {
+    ".py": "Python", ".js": "JavaScript", ".mjs": "JavaScript", ".cjs": "JavaScript",
+    ".jsx": "JavaScript (JSX)", ".ts": "TypeScript", ".tsx": "TypeScript (TSX)",
+    ".java": "Java", ".kt": "Kotlin", ".c": "C", ".h": "C/C++ Header", ".hpp": "C/C++ Header",
+    ".cpp": "C++", ".cc": "C++", ".cs": "C#", ".go": "Go", ".rs": "Rust", ".rb": "Ruby",
+    ".php": "PHP", ".swift": "Swift", ".lua": "Lua", ".sh": "Shell", ".bash": "Shell",
+    ".ps1": "PowerShell", ".bat": "Batch", ".cmd": "Batch", ".html": "HTML", ".htm": "HTML",
+    ".css": "CSS", ".scss": "SCSS", ".sass": "SCSS", ".less": "Less", ".json": "JSON",
+    ".yml": "YAML", ".yaml": "YAML", ".toml": "TOML", ".xml": "XML", ".md": "Markdown",
+    ".txt": "Text", ".sql": "SQL", ".vue": "Vue", ".svelte": "Svelte", ".dart": "Dart",
+    ".r": "R", ".mcfunction": "mcfunction", ".ini": "INI", ".cfg": "Config", ".gradle": "Gradle",
+}
+NAMES = {"dockerfile": "Dockerfile", "makefile": "Makefile"}
+MAX_READ = 5 * 1024 * 1024
+
+
+def language_of(path: Path) -> str:
+    n = path.name.lower()
+    if n in NAMES:
+        return NAMES[n]
+    return LANGS.get(path.suffix.lower(), "Other")
+
+
+def collect(folder: Path, files: List[Path]) -> dict:
+    langs = {}  # type: Dict[str, List[int]]
+    biggest = []
+    total = {"files": 0, "text_files": 0, "lines": 0, "blank": 0, "bytes": 0, "skipped": 0}
+    for rel in files:
+        full = folder / rel
+        try:
+            size = full.stat().st_size
+        except OSError:
+            continue
+        total["files"] += 1
+        total["bytes"] += size
+        if size > MAX_READ:
+            total["skipped"] += 1
+            continue
+        try:
+            data = full.read_bytes()
+        except OSError:
+            continue
+        if b"\0" in data[:8192]:
+            total["skipped"] += 1
+            continue
+        lines = data.count(b"\n") + (1 if data and not data.endswith(b"\n") else 0)
+        blank = sum(1 for ln in data.splitlines() if not ln.strip())
+        lang = language_of(rel)
+        entry = langs.setdefault(lang, [0, 0, 0])
+        entry[0] += 1
+        entry[1] += lines
+        entry[2] += lines - blank
+        total["text_files"] += 1
+        total["lines"] += lines
+        total["blank"] += blank
+        biggest.append((lines, rel.as_posix(), size))
+    biggest.sort(reverse=True)
+    return {"langs": langs, "biggest": biggest, "total": total}
+
+
+def git_stats(folder: Path, top: int, known: set) -> Optional[dict]:
+    if not is_git_repo(folder):
+        return None
+    try:
+        commits = int(git(folder, "rev-list", "--count", "HEAD", check=False).strip() or 0)
+    except ValueError:
+        commits = 0
+    if commits == 0:
+        return None
+    contributors = []
+    for line in git(folder, "shortlog", "-sn", "--no-merges", "HEAD", check=False).splitlines():
+        if "\t" in line:
+            n, name = line.strip().split("\t", 1)
+            contributors.append((name.strip(), int(n)))
+    roots = [d for d in git(folder, "log", "--max-parents=0", "--format=%ad", "--date=short",
+                            check=False).split() if d]
+    last = git(folder, "log", "-1", "--format=%ad", "--date=short", check=False).strip()
+    churn = Counter()
+    out = git(folder, "log", "-n", "3000", "--name-only", "--pretty=format:", "--relative", check=False)
+    for line in out.splitlines():
+        line = line.strip()
+        if line and line in known:
+            churn[line] += 1
+    return {"commits": commits, "contributors": contributors, "first": min(roots) if roots else "?",
+            "last": last, "most_changed": churn.most_common(top)}
+
+
+def health(folder: Path) -> List[tuple]:
+    names = {n.lower() for n in os.listdir(str(folder))}
+    has_tests = any(n in names for n in ("tests", "test", "__tests__", "spec")) or any(
+        n.startswith("test_") for n in names)
+    return [
+        ("README", any(n.startswith("readme") for n in names)),
+        ("LICENSE", any(n.startswith(("license", "licence", "copying")) for n in names)),
+        (".gitignore", ".gitignore" in names),
+        ("Tests", has_tests),
+        ("CI config", (folder / ".github" / "workflows").is_dir() or ".gitlab-ci.yml" in names),
+    ]
+
+
+def run(args: argparse.Namespace) -> int:
+    folder = resolve_folder(args.folder)
+    files = list_project_files(folder)
+    data = collect(folder, files)
+    known = {f.as_posix() for f in files}
+    gs = git_stats(folder, args.top, known)
+    hc = health(folder)
+    t = data["total"]
+    langs = sorted(data["langs"].items(), key=lambda kv: kv[1][1], reverse=True)
+
+    if args.json:
+        print(json.dumps({
+            "folder": str(folder), "totals": t,
+            "languages": {k: {"files": v[0], "lines": v[1], "code_lines": v[2]} for k, v in langs},
+            "largest_files": [{"path": p, "lines": l, "bytes": s} for l, p, s in data["biggest"][:args.top]],
+            "git": gs, "health": {k: v for k, v in hc},
+        }, indent=2))
+        return 0
+
+    print()
+    print(c("  RepoStats", "bold") + " - " + c(folder.name, "cyan"))
+    print(c("  " + str(folder), "dim"))
+    print()
+    print(c("  Overview", "bold"))
+    print("    Files      %s  (%s)" % (human_num(t["files"]), human_size(t["bytes"])))
+    print("    Lines      %s  (code %s, blank %s)" % (
+        human_num(t["lines"]), human_num(t["lines"] - t["blank"]), human_num(t["blank"])))
+    print("    Languages  %d" % len(langs))
+    if t["skipped"]:
+        print(c("    (%d binary/huge files not counted for lines)" % t["skipped"], "dim"))
+    print()
+    if langs:
+        print(c("  Languages", "bold"))
+        mx = max(v[1] for _, v in langs) or 1
+        for name, (nf, nl, _) in langs[:12]:
+            pct = 100.0 * nl / t["lines"] if t["lines"] else 0
+            print("    %-18s %5s %-5s %9s lines %5.1f%%  %s" % (name, human_num(nf), "file" if nf == 1 else "files", human_num(nl), pct,
+                                                               c(bar(nl, mx, 16), "cyan")))
+        print()
+    if data["biggest"]:
+        print(c("  Largest files (by lines)", "bold"))
+        for lines, path, size in data["biggest"][:args.top]:
+            print("    %7s  %s" % (human_num(lines), path))
+        print()
+    if gs:
+        print(c("  Git", "bold"))
+        print("    Commits    %s   (%s -> %s)" % (human_num(gs["commits"]), gs["first"], gs["last"]))
+        print("    Authors    %d" % len(gs["contributors"]))
+        for name, n in gs["contributors"][:args.top]:
+            print("      %5d  %s" % (n, name))
+        if gs["most_changed"]:
+            print()
+            print(c("  Most changed files", "bold"))
+            for path, n in gs["most_changed"]:
+                print("    %5dx  %s" % (n, path))
+        print()
+    print(c("  Health check", "bold"))
+    for name, ok in hc:
+        print("    %s %s" % (c("✔", "green") if ok else c("✘", "red"), name))
+    print()
+    return 0
+
+
+def register(sub, common) -> None:
+    p = sub.add_parser(
+        "repostats", aliases=["rs"], parents=[common],
+        help="language breakdown, biggest files, git activity",
+        description="Quick stats for any project: lines per language, biggest files,\n"
+                    "most-changed files, contributors and a health checklist.",
+        epilog=EPILOG, formatter_class=argparse.RawDescriptionHelpFormatter)
+    p.add_argument("-f", "--folder", metavar="PATH", help="project folder (default: current folder)")
+    p.add_argument("-n", "--top", type=int, default=5, metavar="N", help="rows in top-N lists (default 5)")
+    p.add_argument("--json", action="store_true", help="output JSON")
+    p.set_defaults(func=run)
+
+
+META = ("Project & Code", "repostats", "rs", "lines per language, biggest files, git activity, health")

devkittools/tools/secrets_scan.py

@@ -0,0 +1,108 @@
+"""dkt secrets (sec) - scan a project for accidentally committed secrets."""
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import re
+from collections import Counter
+
+from ..utils import c, fail, is_binary_chunk, list_project_files, ok, resolve_folder, sym, warn
+
+META = ("Project & Code", "secrets", "sec", "scan for leaked API keys, tokens, private keys")
+
+EPILOG = """\
+examples:
+  dkt sec                     scan the current project
+  dkt sec --entropy           also flag random-looking strings assigned to keys
+  dkt sec --json              for CI; exits 1 when something is found
+Values are always masked in the output.
+"""
+
+PATTERNS = [
+    ("AWS access key", re.compile(r"\b(AKIA|ASIA)[0-9A-Z]{16}\b")),
+    ("GitHub token", re.compile(r"\b(ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{36,}\b")),
+    ("GitHub fine-grained token", re.compile(r"\bgithub_pat_[A-Za-z0-9_]{50,}\b")),
+    ("Slack token", re.compile(r"\bxox[abprs]-[A-Za-z0-9-]{10,}\b")),
+    ("Stripe live key", re.compile(r"\b[sr]k_live_[A-Za-z0-9]{16,}\b")),
+    ("Google API key", re.compile(r"\bAIza[0-9A-Za-z_\-]{35}\b")),
+    ("OpenAI-style key", re.compile(r"\bsk-[A-Za-z0-9_\-]{32,}\b")),
+    ("Anthropic key", re.compile(r"\bsk-ant-[A-Za-z0-9_\-]{20,}\b")),
+    ("Private key block", re.compile(r"-----BEGIN (?:RSA |EC |DSA |OPENSSH |PGP )?PRIVATE KEY-----")),
+    ("JWT", re.compile(r"\beyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b")),
+    ("Discord bot token", re.compile(r"\b[MNO][A-Za-z\d_-]{23,25}\.[\w-]{6}\.[\w-]{27,}\b")),
+    ("Connection string with password", re.compile(r"\b[a-z][a-z0-9+.-]*://[^\s:/@]+:[^\s:/@]{3,}@[^\s/]+")),
+]
+ASSIGN_RE = re.compile(r"""(?i)\b([a-z0-9_]*(?:secret|token|passw(?:or)?d|api[_-]?key|apikey|auth)[a-z0-9_]*)\b\s*[:=]\s*['"]([^'"\s]{8,})['"]""")
+SKIP_EXT = {".png", ".jpg", ".jpeg", ".gif", ".ico", ".svg", ".woff", ".woff2", ".ttf", ".pdf", ".zip", ".lock", ".min.js", ".map"}
+PLACEHOLDER = re.compile(r"(?i)(example|your[_-]|xxx|changeme|placeholder|<.*>|\$\{|{{|dummy|sample|test|\*{3,})")
+
+
+def entropy(s: str) -> float:
+    if not s:
+        return 0.0
+    n = len(s)
+    return -sum(v / n * math.log2(v / n) for v in Counter(s).values())
+
+
+def masked(v: str) -> str:
+    return v[:4] + "*" * 6 + v[-2:] if len(v) > 10 else "*" * len(v)
+
+
+def run(args) -> int:
+    folder = resolve_folder(args.folder)
+    findings = []
+    scanned = 0
+    for rel in list_project_files(folder):
+        p = folder / rel
+        if p.suffix.lower() in SKIP_EXT or p.name.endswith(".min.js"):
+            continue
+        try:
+            if p.stat().st_size > 1_000_000:
+                continue
+            raw = p.read_bytes()
+        except OSError:
+            continue
+        if is_binary_chunk(raw[:4096]):
+            continue
+        scanned += 1
+        text = raw.decode("utf-8", errors="replace")
+        for i, line in enumerate(text.splitlines(), 1):
+            if len(line) > 2000:
+                continue
+            line_hit = False
+            for label, rx in PATTERNS:
+                m = rx.search(line)
+                if m:
+                    line_hit = True
+                    findings.append((str(rel).replace("\\", "/"), i, label, masked(m.group(0))))
+            if args.entropy and not line_hit:
+                for m in ASSIGN_RE.finditer(line):
+                    val = m.group(2)
+                    if not PLACEHOLDER.search(val) and entropy(val) > 3.5:
+                        findings.append((str(rel).replace("\\", "/"), i, "high-entropy %s" % m.group(1), masked(val)))
+        if p.name.startswith(".env") and p.name not in (".env.example", ".env.sample", ".env.template"):
+            findings.append((str(rel).replace("\\", "/"), 0, ".env file in project (is it git-ignored?)", ""))
+    if args.json:
+        print(json.dumps([dict(zip(("file", "line", "type", "value"), f)) for f in findings], indent=2))
+        return 1 if findings else 0
+    if not findings:
+        ok("no secrets found (%d files scanned)" % scanned)
+        return 0
+    for fpath, line, label, val in findings:
+        loc = "%s:%s" % (fpath, line) if line else fpath
+        print("  %s %s  %s  %s" % (c(sym("fail"), "bred"), c(label, "bold"), c(loc, "bcyan"), c(val, "gray")))
+    print()
+    warn("%d potential secret%s in %d files. Rotate anything real, then remove it from git history." % (
+        len(findings), "" if len(findings) == 1 else "s", scanned))
+    return 1
+
+
+def register(sub, common) -> None:
+    p = sub.add_parser("secrets", aliases=["sec"], parents=[common], help=META[3],
+                       description="Scan for leaked credentials (respects .gitignore).",
+                       epilog=EPILOG, formatter_class=argparse.RawDescriptionHelpFormatter)
+    p.add_argument("-f", "--folder", metavar="PATH")
+    p.add_argument("--entropy", action="store_true", help="also flag high-entropy values assigned to key/secret/token names")
+    p.add_argument("--json", action="store_true")
+    p.set_defaults(func=run)

devkittools/tools/serve.py

@@ -0,0 +1,118 @@
+"""dkt serve (sv) - instant static file server with CORS, SPA mode and LAN URL."""
+from __future__ import annotations
+
+import argparse
+import functools
+import http.server
+import socket
+import socketserver
+import threading
+import time
+import webbrowser
+from pathlib import Path
+
+from ..utils import DktError, box, c, resolve_folder, sym
+
+META = ("Servers & Network", "serve", "sv", "static file server: CORS, SPA mode, LAN URL, open browser")
+
+EPILOG = """\
+examples:
+  dkt sv                      serve the current folder on :8000
+  dkt sv -p 3000 --open       pick a port and open the browser
+  dkt sv public --spa         single-page-app mode (unknown paths -> index.html)
+  dkt sv --cors --no-cache    handy for front-end work
+"""
+
+
+def lan_ip() -> str:
+    try:
+        s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+        s.connect(("10.255.255.255", 1))
+        ip = s.getsockname()[0]
+        s.close()
+        return ip
+    except Exception:
+        return "127.0.0.1"
+
+
+def make_handler(root: Path, cors: bool, spa: bool, no_cache: bool, quiet: bool):
+    class Handler(http.server.SimpleHTTPRequestHandler):
+        def end_headers(self):
+            if cors:
+                self.send_header("Access-Control-Allow-Origin", "*")
+                self.send_header("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS")
+                self.send_header("Access-Control-Allow-Headers", "*")
+            if no_cache:
+                self.send_header("Cache-Control", "no-store, must-revalidate")
+            super().end_headers()
+
+        def do_OPTIONS(self):
+            self.send_response(204)
+            self.end_headers()
+
+        def send_head(self):
+            if spa:
+                path = Path(self.translate_path(self.path))
+                if not path.exists() and "." not in Path(self.path.split("?")[0]).name:
+                    self.path = "/index.html"
+            return super().send_head()
+
+        def log_message(self, fmt, *args):
+            if quiet:
+                return
+            code = str(args[1]) if len(args) > 1 else ""
+            col = "bgreen" if code.startswith("2") else "byellow" if code.startswith(("3", "1")) else "bred"
+            print("  %s  %s  %s" % (c(time.strftime("%H:%M:%S"), "gray"), c(code, col), args[0] if args else ""))
+    return functools.partial(Handler, directory=str(root))
+
+
+def run(args) -> int:
+    root = resolve_folder(args.folder)
+    handler = make_handler(root, args.cors, args.spa, args.no_cache, args.quiet)
+
+    class Server(socketserver.ThreadingMixIn, http.server.HTTPServer):
+        daemon_threads = True
+        allow_reuse_address = True
+
+    port = args.port
+    srv = None
+    for p in range(port, port + 20):
+        try:
+            srv = Server((args.host, p), handler)
+            port = p
+            break
+        except OSError:
+            continue
+    if srv is None:
+        raise DktError("Ports %d-%d are all busy. Try 'dkt pk --show %d'." % (args.port, args.port + 19, args.port))
+    lines = ["%s  http://localhost:%d" % (c("local  ", "gray"), port)]
+    if args.host in ("0.0.0.0", ""):
+        lines.append("%s  http://%s:%d" % (c("network", "gray"), lan_ip(), port))
+    lines += ["", c("serving ", "gray") + str(root), c("Ctrl+C to stop", "gray")]
+    if port != args.port:
+        lines.insert(0, c("port %d was busy, using %d" % (args.port, port), "yellow"))
+    box("dkt serve", lines)
+    if args.open:
+        threading.Timer(0.4, lambda: webbrowser.open("http://localhost:%d" % port)).start()
+    try:
+        srv.serve_forever()
+    except KeyboardInterrupt:
+        print("\n  stopped.")
+    finally:
+        srv.server_close()
+    return 0
+
+
+def register(sub, common) -> None:
+    p = sub.add_parser("serve", aliases=["sv"], parents=[common], help=META[3],
+                       description="Serve a folder over HTTP.", epilog=EPILOG,
+                       formatter_class=argparse.RawDescriptionHelpFormatter)
+    p.add_argument("folder", nargs="?", help="folder to serve (default: current)")
+    p.add_argument("-p", "--port", type=int, default=8000)
+    p.add_argument("--host", default="0.0.0.0", help="bind address (default 0.0.0.0; use 127.0.0.1 for local only)")
+    p.add_argument("--cors", action="store_true", help="send permissive CORS headers")
+    p.add_argument("--spa", action="store_true", help="fallback to index.html for unknown routes")
+    p.add_argument("--no-cache", action="store_true", help="disable browser caching")
+    p.add_argument("--open", action="store_true", help="open in the default browser")
+    p.add_argument("-q", "--quiet", action="store_true", help="don't log requests")
+    p.set_defaults(func=run)

devkittools/tools/snip.py

@@ -0,0 +1,94 @@
+"""dkt snip - a personal snippet / command notebook that lives in your terminal."""
+from __future__ import annotations
+
+import argparse
+import sys
+
+from ..utils import (DktError, c, config_dir, copy_to_clipboard, info, load_json_file, ok, read_input,
+                     save_json_file, sym, table)
+
+META = ("Data & Text", "snip", "", "save & recall snippets / commands (copy to clipboard)")
+
+EPILOG = """\
+examples:
+  dkt snip add deploy "ssh me@host 'cd app && git pull'"
+  dkt snip add sql-dump --paste              save from clipboard
+  echo "some text" | dkt snip add note1
+  dkt snip get deploy --copy
+  dkt snip ls                                all snippets
+  dkt snip ls ssh                            search names and content
+  dkt snip rm deploy
+"""
+
+
+def _path():
+    return config_dir() / "snippets.json"
+
+
+def _load():
+    return load_json_file(_path(), {})
+
+
+def cmd_add(args) -> int:
+    text = read_input(args.text, None, args.paste, "snippet text")
+    data = _load()
+    existed = args.name in data
+    data[args.name] = text.rstrip("\n")
+    save_json_file(_path(), data)
+    ok("%s snippet '%s' (%d chars)" % ("updated" if existed else "saved", args.name, len(text)))
+    return 0
+
+
+def cmd_get(args) -> int:
+    data = _load()
+    if args.name not in data:
+        close = [k for k in data if args.name.lower() in k.lower()]
+        raise DktError("No snippet named '%s'.%s" % (args.name, (" Did you mean: " + ", ".join(close)) if close else ""))
+    print(data[args.name])
+    if args.copy and copy_to_clipboard(data[args.name]):
+        info(c("%s copied to clipboard" % sym("ok"), "green"))
+    return 0
+
+
+def cmd_ls(args) -> int:
+    data = _load()
+    q = (args.query or "").lower()
+    rows = [(c(k, "bold bcyan"), v.replace("\n", " ")[:70]) for k, v in sorted(data.items())
+            if not q or q in k.lower() or q in v.lower()]
+    if not rows:
+        print("  no snippets%s" % (" matching '%s'" % q if q else " yet - add one with: dkt snip add NAME TEXT"))
+        return 0
+    table(["NAME", "PREVIEW"], rows)
+    return 0
+
+
+def cmd_rm(args) -> int:
+    data = _load()
+    if args.name not in data:
+        raise DktError("No snippet named '%s'." % args.name)
+    del data[args.name]
+    save_json_file(_path(), data)
+    ok("removed '%s'" % args.name)
+    return 0
+
+
+def register(sub, common) -> None:
+    p = sub.add_parser("snip", parents=[common], help=META[3], description="Personal snippet store.",
+                       epilog=EPILOG, formatter_class=argparse.RawDescriptionHelpFormatter)
+    p.set_defaults(func=lambda a: (p.print_help() or 0))
+    g = p.add_subparsers(dest="sub", metavar="<add|get|ls|rm>")
+    a = g.add_parser("add", help="save a snippet")
+    a.add_argument("name")
+    a.add_argument("text", nargs="?")
+    a.add_argument("--paste", action="store_true", help="take text from the clipboard")
+    a.set_defaults(func=cmd_add)
+    gt = g.add_parser("get", help="print (and optionally copy) a snippet")
+    gt.add_argument("name")
+    gt.add_argument("--copy", action="store_true")
+    gt.set_defaults(func=cmd_get)
+    ls = g.add_parser("ls", aliases=["list"], help="list / search snippets")
+    ls.add_argument("query", nargs="?")
+    ls.set_defaults(func=cmd_ls)
+    rm = g.add_parser("rm", help="delete a snippet")
+    rm.add_argument("name")
+    rm.set_defaults(func=cmd_rm)

devkittools/tools/system.py

@@ -0,0 +1,157 @@
+"""dkt update / config / completion / about - the toolkit's own housekeeping commands."""
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+import urllib.request
+from pathlib import Path
+
+from ..utils import (DktError, Spinner, banner, box, c, config_dir, info, kv, load_config, ok, save_json_file,
+                     sym, warn)
+
+META = ("dkt itself", "update", "", "upgrade dkt to the newest version from PyPI")
+
+PKG = "dktcli"
+
+
+def _ver(s: str):
+    out = []
+    for part in s.split("."):
+        digits = "".join(ch for ch in part if ch.isdigit())
+        out.append(int(digits) if digits else 0)
+    return tuple(out)
+
+
+def latest_version(timeout: float = 6.0):
+    req = urllib.request.Request("https://pypi.org/pypi/%s/json" % PKG, headers={"User-Agent": "dkt-update"})
+    with urllib.request.urlopen(req, timeout=timeout) as r:
+        return json.loads(r.read().decode())["info"]["version"]
+
+
+def source_checkout():
+    root = Path(__file__).resolve().parents[3]
+    return root if (root / ".git").exists() and (root / "pyproject.toml").exists() else None
+
+
+def run_update(args) -> int:
+    from .. import __version__
+    src = source_checkout()
+    if src and not args.force:
+        warn("dkt is running from a source checkout (%s)." % src)
+        print("  Update it with:  update.bat   (or: git pull && pip install -e .)")
+        return 0
+    try:
+        with Spinner("checking PyPI"):
+            latest = latest_version()
+    except Exception:
+        latest = None
+    if latest:
+        if _ver(latest) <= _ver(__version__) and not args.force:
+            ok("already up to date (v%s)" % __version__)
+            return 0
+        print("  v%s  %s  v%s" % (__version__, c(sym("arrow"), "bcyan"), c(latest, "bold bgreen")))
+    else:
+        info(c("could not reach PyPI - trying pip anyway", "yellow"))
+    if args.check:
+        return 0
+    with Spinner("upgrading"):
+        r = subprocess.run([sys.executable, "-m", "pip", "install", "--upgrade", PKG],
+                           stdout=subprocess.PIPE, stderr=subprocess.STDOUT)
+    if r.returncode != 0:
+        print(r.stdout.decode("utf-8", errors="replace")[-1500:])
+        raise DktError("pip upgrade failed. Try:  python -m pip install --upgrade %s" % PKG)
+    ok("updated! Run 'dkt --version' to confirm.")
+    return 0
+
+
+def run_config(args) -> int:
+    cfg = load_config()
+    path = config_dir() / "config.json"
+    act = args.action or "list"
+    if act == "path":
+        print(path)
+    elif act == "list":
+        if not cfg:
+            print("  no settings yet.  Try: dkt config set author \"Your Name\"")
+            print(c("  known keys: author, model (Ollama model for commit writer)", "gray"))
+        else:
+            kv(sorted(cfg.items()), key_color="bcyan")
+    elif act == "get":
+        if not args.key or args.key not in cfg:
+            raise DktError("Setting '%s' is not set." % args.key)
+        print(cfg[args.key])
+    elif act == "set":
+        if not args.key or args.value is None:
+            raise DktError("Usage: dkt config set KEY VALUE")
+        cfg[args.key] = args.value
+        save_json_file(path, cfg)
+        ok("%s = %s" % (args.key, args.value))
+    elif act == "unset":
+        if args.key in cfg:
+            del cfg[args.key]
+            save_json_file(path, cfg)
+        ok("removed %s" % args.key)
+    return 0
+
+
+def run_about(args) -> int:
+    from .. import __version__
+    banner()
+    box("tips", [
+        "%s  %s" % (c("dkt menu", "bold bcyan"), "interactive launcher"),
+        "%s  %s" % (c("dkt <tool> -h", "bold bcyan"), "help + examples for any tool"),
+        "%s  %s" % (c("dkt doctor", "bold bcyan"), "check your dev environment"),
+        "%s  %s" % (c("dkt completion", "bold bcyan"), "tab-completion for your shell"),
+        "%s  %s" % (c("dkt update", "bold bcyan"), "get the latest version"),
+    ])
+    return 0
+
+
+def _names(parser_sub):
+    return sorted(parser_sub.choices)
+
+
+def run_completion(args, sub) -> int:
+    names = " ".join(_names(sub))
+    shell = args.shell
+    if shell == "bash":
+        print('_dkt() { COMPREPLY=( $(compgen -W "%s" -- "${COMP_WORDS[1]}") ); }\ncomplete -F _dkt dkt' % names)
+        print("# add to ~/.bashrc:  eval \"$(dkt completion bash)\"", file=sys.stderr)
+    elif shell == "zsh":
+        print("_dkt() { reply=(%s) }\ncompctl -K _dkt dkt" % names)
+        print("# add to ~/.zshrc:  eval \"$(dkt completion zsh)\"", file=sys.stderr)
+    else:
+        quoted = ",".join("'%s'" % n for n in _names(sub))
+        print("Register-ArgumentCompleter -Native -CommandName dkt -ScriptBlock {\n"
+              "    param($wordToComplete, $commandAst, $cursorPosition)\n"
+              "    @(%s) | Where-Object { $_ -like \"$wordToComplete*\" } |\n"
+              "        ForEach-Object { [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_) }\n"
+              "}" % quoted)
+        print("# add to your profile:  dkt completion powershell | Out-String | Add-Content $PROFILE", file=sys.stderr)
+    return 0
+
+
+def register(sub, common) -> None:
+    u = sub.add_parser("update", aliases=["upgrade"], parents=[common], help=META[3],
+                       description="Upgrade dkt using pip.")
+    u.add_argument("--check", action="store_true", help="only check for a newer version")
+    u.add_argument("--force", action="store_true", help="reinstall even if up to date / from source")
+    u.set_defaults(func=run_update)
+
+    cf = sub.add_parser("config", parents=[common], help="view or change dkt settings",
+                        description="Settings live in a small JSON file in your user config folder.")
+    cf.add_argument("action", nargs="?", choices=["list", "get", "set", "unset", "path"])
+    cf.add_argument("key", nargs="?")
+    cf.add_argument("value", nargs="?")
+    cf.set_defaults(func=run_config)
+
+    cp = sub.add_parser("completion", parents=[common], help="print shell tab-completion script",
+                        description="Print a completion script for your shell.")
+    cp.add_argument("shell", nargs="?", choices=["powershell", "bash", "zsh"],
+                    default="powershell" if sys.platform.startswith("win") else "bash")
+    cp.set_defaults(func=lambda a: run_completion(a, sub))
+
+    ab = sub.add_parser("about", parents=[common], help="logo, version and tips")
+    ab.set_defaults(func=run_about)