dktcli 1.0.0__py3-none-any.whl

devkittools/tools/colortool.py

@@ -0,0 +1,126 @@
+"""dkt color (col) - convert colors, preview swatches, check contrast, build palettes."""
+from __future__ import annotations
+
+import argparse
+import colorsys
+import re
+
+from ..utils import DktError, c, color_enabled, kv
+
+META = ("Generate & Convert", "color", "col", "hex/rgb/hsl converter with live swatches + contrast check")
+
+EPILOG = """\
+examples:
+  dkt col "#ff6b35"
+  dkt col rgb(30,144,255)
+  dkt col 120,60,200            plain r,g,b
+  dkt col hsl(210,80%,50%)
+  dkt col tomato                a few CSS names work too
+"""
+
+NAMES = {
+    "black": "#000000", "white": "#ffffff", "red": "#ff0000", "green": "#008000", "blue": "#0000ff",
+    "yellow": "#ffff00", "cyan": "#00ffff", "magenta": "#ff00ff", "orange": "#ffa500", "purple": "#800080",
+    "pink": "#ffc0cb", "gray": "#808080", "grey": "#808080", "tomato": "#ff6347", "gold": "#ffd700",
+    "teal": "#008080", "navy": "#000080", "coral": "#ff7f50", "salmon": "#fa8072", "indigo": "#4b0082",
+    "violet": "#ee82ee", "crimson": "#dc143c", "lime": "#00ff00", "maroon": "#800000", "olive": "#808000",
+    "silver": "#c0c0c0", "skyblue": "#87ceeb", "turquoise": "#40e0d0", "orchid": "#da70d6", "brown": "#a52a2a",
+}
+
+
+def parse_color(s: str):
+    s = s.strip().lower()
+    if s in NAMES:
+        s = NAMES[s]
+    m = re.fullmatch(r"#?([0-9a-f]{3}|[0-9a-f]{6})", s)
+    if m:
+        h = m.group(1)
+        if len(h) == 3:
+            h = "".join(ch * 2 for ch in h)
+        return int(h[0:2], 16), int(h[2:4], 16), int(h[4:6], 16)
+    m = re.fullmatch(r"(?:rgb\()?\s*(\d{1,3})\s*[, ]\s*(\d{1,3})\s*[, ]\s*(\d{1,3})\s*\)?", s)
+    if m:
+        r, g, b = (int(x) for x in m.groups())
+        if max(r, g, b) > 255:
+            raise DktError("RGB values must be 0-255.")
+        return r, g, b
+    m = re.fullmatch(r"hsl\(\s*(\d+(?:\.\d+)?)\s*,\s*(\d+(?:\.\d+)?)%?\s*,\s*(\d+(?:\.\d+)?)%?\s*\)", s)
+    if m:
+        h, sat, l = float(m.group(1)) / 360, float(m.group(2)) / 100, float(m.group(3)) / 100
+        r, g, b = colorsys.hls_to_rgb(h, l, sat)
+        return int(round(r * 255)), int(round(g * 255)), int(round(b * 255))
+    raise DktError("Couldn't parse color '%s'. Try #ff6b35, rgb(255,107,53), hsl(20,100%%,60%%) or a name." % s)
+
+
+def swatch(rgb, width: int = 6) -> str:
+    if not color_enabled():
+        return ""
+    return "\033[48;2;%d;%d;%dm%s\033[0m" % (rgb[0], rgb[1], rgb[2], " " * width)
+
+
+def hexstr(rgb) -> str:
+    return "#%02x%02x%02x" % tuple(rgb)
+
+
+def luminance(rgb) -> float:
+    def ch(v):
+        v /= 255.0
+        return v / 12.92 if v <= 0.03928 else ((v + 0.055) / 1.055) ** 2.4
+    r, g, b = (ch(x) for x in rgb)
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b
+
+
+def contrast(a, b) -> float:
+    la, lb = luminance(a), luminance(b)
+    hi, lo = max(la, lb), min(la, lb)
+    return (hi + 0.05) / (lo + 0.05)
+
+
+def hsl_of(rgb):
+    h, l, s = colorsys.rgb_to_hls(*(x / 255.0 for x in rgb))
+    return h * 360, s * 100, l * 100
+
+
+def from_hsl(h, s, l):
+    r, g, b = colorsys.hls_to_rgb((h % 360) / 360.0, max(0, min(100, l)) / 100.0, max(0, min(100, s)) / 100.0)
+    return int(round(r * 255)), int(round(g * 255)), int(round(b * 255))
+
+
+def run(args) -> int:
+    rgb = parse_color(" ".join(args.color))
+    h, s, l = hsl_of(rgb)
+    print()
+    print("  " + swatch(rgb, 20))
+    print("  " + swatch(rgb, 20))
+    print()
+    kv([("hex", c(hexstr(rgb), "bold")),
+        ("rgb", "rgb(%d, %d, %d)" % rgb),
+        ("hsl", "hsl(%d, %d%%, %d%%)" % (round(h), round(s), round(l))),
+        ("int", str(rgb[0] << 16 | rgb[1] << 8 | rgb[2]))])
+    cw, cb = contrast(rgb, (255, 255, 255)), contrast(rgb, (0, 0, 0))
+
+    def grade(r):
+        return c("AAA", "bgreen") if r >= 7 else c("AA", "green") if r >= 4.5 else c("AA large", "yellow") if r >= 3 else c("fail", "red")
+    print()
+    kv([("on white", "%.2f:1  %s" % (cw, grade(cw))), ("on black", "%.2f:1  %s" % (cb, grade(cb)))])
+    print()
+    rows = [
+        ("shades", [from_hsl(h, s, l * f) for f in (0.2, 0.4, 0.6, 0.8, 1.0)]),
+        ("tints", [from_hsl(h, s, l + (100 - l) * f) for f in (0.0, 0.25, 0.5, 0.75, 0.9)]),
+        ("complement", [rgb, from_hsl(h + 180, s, l)]),
+        ("triad", [rgb, from_hsl(h + 120, s, l), from_hsl(h + 240, s, l)]),
+        ("analogous", [from_hsl(h - 30, s, l), rgb, from_hsl(h + 30, s, l)]),
+    ]
+    for name, cols in rows:
+        print("  %s %s  %s" % (c(name.ljust(11), "gray"), "".join(swatch(x, 4) for x in cols),
+                              c(" ".join(hexstr(x) for x in cols), "gray")))
+    print()
+    return 0
+
+
+def register(sub, common) -> None:
+    p = sub.add_parser("color", aliases=["col"], parents=[common], help=META[3],
+                       description="Convert a color and show swatches, contrast and palettes.",
+                       epilog=EPILOG, formatter_class=argparse.RawDescriptionHelpFormatter)
+    p.add_argument("color", nargs="+", help="#hex, rgb(...), r,g,b, hsl(...) or a name")
+    p.set_defaults(func=run)

devkittools/tools/commitwriter.py

@@ -0,0 +1,199 @@
+"""dkt commitwriter (cw) - write a commit message from your diff using a local Ollama model."""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import subprocess
+import urllib.error
+import urllib.request
+from pathlib import Path
+from typing import List, Optional
+
+from ..utils import get_setting, DktError, c, git, info, require_git_repo, resolve_folder
+
+EPILOG = """\
+examples:
+  dkt cw                         message for your staged changes
+  dkt cw --commit                ...then ask to commit with it
+  dkt cw --commit -y             commit without asking
+  dkt cw --all                   include unstaged changes to tracked files
+  dkt cw --model qwen2.5-coder:7b --style simple
+  dkt cw --hint "fixes the login bug"
+  git commit -m "$(dkt cw --raw)"
+
+Needs Ollama (https://ollama.com) running locally, with at least one model pulled.
+Env vars: DKT_MODEL (default model), OLLAMA_HOST (default http://localhost:11434)
+"""
+
+LOCK_EXCLUDES = [":(exclude)package-lock.json", ":(exclude)yarn.lock", ":(exclude)pnpm-lock.yaml",
+                 ":(exclude)poetry.lock", ":(exclude)Cargo.lock", ":(exclude)composer.lock"]
+
+SYSTEM_CONVENTIONAL = (
+    "You are an expert at writing git commit messages. Given a git diff, write ONE commit message.\n"
+    "Rules:\n"
+    "- Use Conventional Commits: type(scope): subject\n"
+    "- Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore\n"
+    "- Subject: imperative mood, lowercase, no trailing period, max 72 characters\n"
+    "- If the change is non-trivial, add a blank line and then 2-5 short bullets starting with '- ' "
+    "explaining what changed and why\n"
+    "- Describe only what the diff shows. Do not invent details.\n"
+    "- Output ONLY the commit message. No code fences, no quotes, no preamble."
+)
+SYSTEM_SIMPLE = (
+    "You are an expert at writing git commit messages. Given a git diff, write ONE commit message.\n"
+    "Rules:\n"
+    "- First line: imperative mood, capitalized, no trailing period, max 72 characters, no type prefix\n"
+    "- If the change is non-trivial, add a blank line and then 2-4 short bullets starting with '- '\n"
+    "- Describe only what the diff shows. Do not invent details.\n"
+    "- Output ONLY the commit message. No code fences, no quotes, no preamble."
+)
+
+
+def ollama_base(host: Optional[str]) -> str:
+    host = host or os.environ.get("OLLAMA_HOST") or "http://localhost:11434"
+    if not host.startswith("http"):
+        host = "http://" + host
+    return host.replace("0.0.0.0", "127.0.0.1").rstrip("/")
+
+
+def http_json(base: str, path: str, payload: Optional[dict] = None, timeout: int = 300) -> dict:
+    data = json.dumps(payload).encode("utf-8") if payload is not None else None
+    req = urllib.request.Request(base + path, data=data, headers={"Content-Type": "application/json"})
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as r:
+            return json.loads(r.read().decode("utf-8"))
+    except urllib.error.HTTPError as e:
+        body = e.read().decode("utf-8", errors="replace")[:300]
+        raise DktError("Ollama returned HTTP %d: %s" % (e.code, body))
+    except (OSError, ValueError):
+        raise DktError("Could not reach Ollama at %s. Is it running? (start it with: ollama serve)" % base)
+
+
+def pick_model(base: str, wanted: Optional[str]) -> str:
+    if wanted:
+        return wanted
+    data = http_json(base, "/api/tags", timeout=10)
+    names = [m.get("name", "") for m in data.get("models", [])]
+    names = [n for n in names if n and not any(x in n.lower() for x in ("embed", "nomic", "bge"))]
+    if not names:
+        raise DktError("No Ollama models installed. Pull one first, e.g.: ollama pull qwen2.5-coder:7b")
+    coders = [n for n in names if "coder" in n.lower()]
+    return (coders or names)[0]
+
+
+def clean_message(text: str) -> str:
+    text = re.sub(r"<think>.*?</think>", "", text, flags=re.DOTALL)
+    text = text.strip()
+    text = re.sub(r"^```[a-zA-Z]*\n?", "", text)
+    text = re.sub(r"\n?```$", "", text)
+    text = text.strip().strip('"').strip("'").strip()
+    return text
+
+
+def get_diff(folder: Path, include_all: bool) -> "tuple":
+    if include_all:
+        base = ["diff", "HEAD"]
+        if not git(folder, "rev-parse", "--verify", "HEAD", check=False).strip():
+            base = ["diff"]
+    else:
+        base = ["diff", "--staged"]
+    stat = git(folder, *(base + ["--stat"]), check=False)
+    diff = git(folder, *(base + ["--no-color", "--", "."] + LOCK_EXCLUDES), check=False)
+    if not diff.strip():
+        diff = git(folder, *(base + ["--no-color"]), check=False)
+    return stat, diff
+
+
+def generate_message(base: str, model: str, stat: str, diff: str, style: str, hint: Optional[str]) -> str:
+    user = []
+    if hint:
+        user.append("Context from the developer: %s\n" % hint)
+    user.append("Files changed:\n%s\n\nDiff:\n%s" % (stat.strip(), diff))
+    payload = {
+        "model": model, "stream": False, "options": {"temperature": 0.2},
+        "messages": [
+            {"role": "system", "content": SYSTEM_CONVENTIONAL if style == "conventional" else SYSTEM_SIMPLE},
+            {"role": "user", "content": "\n".join(user)},
+        ],
+    }
+    data = http_json(base, "/api/chat", payload)
+    msg = clean_message(((data.get("message") or {}).get("content")) or "")
+    if not msg:
+        raise DktError("The model returned an empty message. Try another --model.")
+    return msg
+
+
+def run(args: argparse.Namespace) -> int:
+    folder = resolve_folder(args.folder)
+    require_git_repo(folder)
+    stat, diff = get_diff(folder, args.all)
+    if not diff.strip():
+        raise DktError("Nothing to describe. Stage changes with 'git add' (or use --all for unstaged tracked changes).")
+    truncated = False
+    if len(diff) > args.max_chars:
+        diff = diff[:args.max_chars] + "\n... [diff truncated]"
+        truncated = True
+
+    base = ollama_base(args.host)
+    model = pick_model(base, args.model or get_setting("model"))
+    info(c("Using model %s" % model, "dim") + (c("  (diff truncated)", "yellow") if truncated else ""))
+    info(c("Thinking...", "dim"))
+    msg = generate_message(base, model, stat, diff, args.style, args.hint)
+
+    if args.raw:
+        print(msg)
+        return 0
+    info("")
+    info(c("Suggested commit message:", "bold"))
+    print(msg)
+    if not args.commit:
+        info("")
+        info(c("Tip: run with --commit to use it directly.", "dim"))
+        return 0
+
+    if not args.yes:
+        try:
+            ans = input("\nCommit with this message? [y/N/e(dit)] ").strip().lower()
+        except EOFError:
+            ans = "n"
+        if ans not in ("y", "yes", "e", "edit"):
+            info("Aborted - nothing committed.")
+            return 1
+        edit = ans in ("e", "edit")
+    else:
+        edit = False
+    cmd = ["git", "-C", str(folder), "commit"]
+    if args.all:
+        cmd.append("-a")
+    if edit:
+        cmd.append("-e")
+    cmd += ["-m", msg]
+    code = subprocess.call(cmd)
+    if code == 0:
+        info(c("✔ Committed", "green"))
+    return code
+
+
+def register(sub, common) -> None:
+    p = sub.add_parser(
+        "commitwriter", aliases=["cw"], parents=[common],
+        help="write a commit message from your diff (local Ollama)",
+        description="Reads your staged git diff and asks a local Ollama model to write a\n"
+                    "clean commit message. Works fully offline.",
+        epilog=EPILOG, formatter_class=argparse.RawDescriptionHelpFormatter)
+    p.add_argument("-f", "--folder", metavar="PATH", help="project folder (default: current folder)")
+    p.add_argument("-m", "--model", metavar="NAME", help="Ollama model (default: $DKT_MODEL or first installed)")
+    p.add_argument("--host", metavar="URL", help="Ollama server (default: $OLLAMA_HOST or http://localhost:11434)")
+    p.add_argument("--style", choices=["conventional", "simple"], default="conventional", help="message style")
+    p.add_argument("--hint", metavar="TEXT", help="extra context for the model")
+    p.add_argument("-a", "--all", action="store_true", help="include unstaged changes to tracked files")
+    p.add_argument("-c", "--commit", action="store_true", help="offer to commit with the message")
+    p.add_argument("-y", "--yes", action="store_true", help="with --commit, don't ask for confirmation")
+    p.add_argument("--raw", action="store_true", help="print only the message (for scripts)")
+    p.add_argument("--max-chars", type=int, default=12000, metavar="N", help="max diff characters sent (default 12000)")
+    p.set_defaults(func=run)
+
+
+META = ("AI Helpers", "commitwriter", "cw", "write commit messages from your diff with local Ollama")

devkittools/tools/contextpacker.py

@@ -0,0 +1,226 @@
+"""dkt projectcontextpacker (pcp) - pack a project into one prompt-friendly file."""
+from __future__ import annotations
+
+import argparse
+import fnmatch
+import sys
+from collections import Counter
+from pathlib import Path
+from typing import Dict, List, Optional
+
+from ..utils import (DktError, c, copy_to_clipboard, human_num, info, is_binary_chunk,
+                     list_project_files, resolve_folder)
+
+EPILOG = """\
+examples:
+  dkt pcp                              pack the current folder -> <name>-context.md
+  dkt pcp --folder "C:\\code\\app" --copy
+  dkt pcp --max-tokens 50000           stay under a token budget
+  dkt pcp --include .py .md            only these extensions
+  dkt pcp --exclude "tests/*" "*.svg"  skip patterns
+  dkt pcp --format xml --stdout
+"""
+
+BINARY_EXT = {
+    ".png", ".jpg", ".jpeg", ".gif", ".bmp", ".ico", ".webp", ".tiff", ".psd", ".mp3", ".wav",
+    ".ogg", ".flac", ".mp4", ".mov", ".avi", ".mkv", ".webm", ".zip", ".tar", ".gz", ".7z",
+    ".rar", ".bz2", ".xz", ".exe", ".dll", ".so", ".dylib", ".bin", ".class", ".jar", ".pyc",
+    ".pyo", ".woff", ".woff2", ".ttf", ".otf", ".eot", ".pdf", ".o", ".a", ".lib", ".iso",
+    ".db", ".sqlite", ".mcpack", ".mcaddon", ".nbt", ".dat",
+}
+SKIP_NAMES = {
+    "package-lock.json", "yarn.lock", "pnpm-lock.yaml", "poetry.lock", "cargo.lock",
+    "composer.lock", "gemfile.lock", "pipfile.lock", "bun.lockb", ".ds_store", "thumbs.db",
+}
+FENCE_LANG = {
+    ".py": "python", ".js": "javascript", ".mjs": "javascript", ".jsx": "jsx", ".ts": "typescript",
+    ".tsx": "tsx", ".java": "java", ".kt": "kotlin", ".c": "c", ".h": "c", ".cpp": "cpp",
+    ".cs": "csharp", ".go": "go", ".rs": "rust", ".rb": "ruby", ".php": "php", ".sh": "bash",
+    ".ps1": "powershell", ".bat": "bat", ".html": "html", ".css": "css", ".json": "json",
+    ".yml": "yaml", ".yaml": "yaml", ".toml": "toml", ".md": "markdown", ".sql": "sql",
+    ".xml": "xml", ".vue": "vue", ".lua": "lua",
+}
+
+
+def count_tokens(text: str) -> int:
+    try:
+        import tiktoken  # type: ignore
+        return len(tiktoken.get_encoding("cl100k_base").encode(text, disallowed_special=()))
+    except Exception:
+        return max(1, len(text) // 4) if text else 0
+
+
+def build_tree(paths: List[Path]) -> List[str]:
+    root = {}  # type: dict
+    for p in paths:
+        node = root
+        for part in p.parts[:-1]:
+            node = node.setdefault(part, {})
+        node[p.parts[-1]] = None
+    lines = []  # type: List[str]
+
+    def walk(node: dict, prefix: str) -> None:
+        items = sorted(node.items(), key=lambda kv: (kv[1] is None, kv[0].lower()))
+        for i, (name, child) in enumerate(items):
+            last = i == len(items) - 1
+            lines.append(prefix + ("└── " if last else "├── ") + name + ("/" if child is not None else ""))
+            if child is not None:
+                walk(child, prefix + ("    " if last else "│   "))
+
+    walk(root, "")
+    return lines
+
+
+def _matches(rel: Path, patterns: List[str]) -> bool:
+    posix = rel.as_posix()
+    for pat in patterns:
+        if fnmatch.fnmatch(posix, pat) or fnmatch.fnmatch(rel.name, pat):
+            return True
+        if pat.endswith("/") and posix.startswith(pat):
+            return True
+    return False
+
+
+def render(name: str, entries: List[dict], fmt: str) -> str:
+    tree = build_tree([e["rel"] for e in entries])
+    if fmt == "xml":
+        out = ["<project name=\"%s\">" % name, "<directory_structure>", "%s/" % name]
+        out += tree
+        out += ["</directory_structure>", "<files>"]
+        for e in entries:
+            out.append("<file path=\"%s\">" % e["rel"].as_posix())
+            out.append(e["text"].rstrip("\n"))
+            out.append("</file>")
+        out += ["</files>", "</project>"]
+        return "\n".join(out) + "\n"
+    out = ["# Project: %s" % name, "", "_Packed with devkittools `dkt pcp`_", "",
+           "## Directory structure", "", "```", "%s/" % name]
+    out += tree
+    out += ["```", "", "## Files", ""]
+    for e in entries:
+        fence = "```"
+        while fence in e["text"]:
+            fence += "`"
+        out.append("### %s" % e["rel"].as_posix())
+        out.append("")
+        out.append(fence + FENCE_LANG.get(e["rel"].suffix.lower(), ""))
+        out.append(e["text"].rstrip("\n"))
+        out.append(fence)
+        out.append("")
+    return "\n".join(out)
+
+
+def run(args: argparse.Namespace) -> int:
+    folder = resolve_folder(args.folder)
+    ext = "xml" if args.format == "xml" else "md"
+    out_path = Path(args.output).resolve() if args.output else Path.cwd() / ("%s-context.%s" % (folder.name, ext))
+    include = [("." + e.lstrip(".")).lower() for e in (args.include or [])]
+    exclude = args.exclude or []
+    max_bytes = int(args.max_file_kb * 1024)
+
+    skipped = Counter()  # type: Counter
+    candidates = []  # type: List[dict]
+    for rel in list_project_files(folder):
+        full = folder / rel
+        if full.resolve() == out_path:
+            continue
+        low = rel.name.lower()
+        if low in SKIP_NAMES:
+            skipped["lock/system files"] += 1
+            continue
+        if rel.suffix.lower() in BINARY_EXT:
+            skipped["binary files"] += 1
+            continue
+        if low.endswith((".min.js", ".min.css", ".map")):
+            skipped["minified/map files"] += 1
+            continue
+        if include and rel.suffix.lower() not in include:
+            skipped["not in --include"] += 1
+            continue
+        if exclude and _matches(rel, exclude):
+            skipped["matched --exclude"] += 1
+            continue
+        try:
+            size = full.stat().st_size
+            if size > max_bytes:
+                skipped["too large (> %g KB)" % args.max_file_kb] += 1
+                continue
+            raw = full.read_bytes()
+        except OSError:
+            skipped["unreadable"] += 1
+            continue
+        if is_binary_chunk(raw[:8192]):
+            skipped["binary files"] += 1
+            continue
+        text = raw.decode("utf-8", errors="replace")
+        if not text.strip():
+            skipped["empty files"] += 1
+            continue
+        candidates.append({"rel": rel, "text": text, "tokens": count_tokens(text)})
+
+    if not candidates:
+        raise DktError("No files to pack in %s (after filtering)." % folder)
+
+    selected = candidates
+    if args.max_tokens:
+        selected = []
+        running = 400
+        for e in sorted(candidates, key=lambda e: (len(e["rel"].parts), e["rel"].as_posix())):
+            cost = e["tokens"] + 30
+            if running + cost > args.max_tokens:
+                skipped["over --max-tokens budget"] += 1
+                continue
+            running += cost
+            selected.append(e)
+        if not selected:
+            raise DktError("--max-tokens %d is too small to fit any file." % args.max_tokens)
+    selected.sort(key=lambda e: e["rel"].as_posix())
+
+    doc = render(folder.name, selected, args.format)
+    total_tokens = count_tokens(doc)
+
+    if args.stdout:
+        sys.stdout.write(doc)
+    else:
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+        out_path.write_text(doc, encoding="utf-8")
+    if args.copy:
+        if copy_to_clipboard(doc):
+            info(c("✔ Copied to clipboard", "green"))
+        else:
+            info(c("! Could not access the clipboard", "yellow"))
+
+    info("")
+    if not args.stdout:
+        info("%s %s" % (c("✔ Packed ->", "green"), out_path))
+    info("  Files included : %s" % human_num(len(selected)))
+    info("  Total size     : %s chars, ~%s tokens" % (human_num(len(doc)), human_num(total_tokens)))
+    if skipped:
+        info("  Skipped        : " + ", ".join("%d %s" % (n, why) for why, n in skipped.items()))
+    info("  Biggest files  :")
+    for e in sorted(selected, key=lambda e: e["tokens"], reverse=True)[:5]:
+        info("    %8s tokens  %s" % (human_num(e["tokens"]), e["rel"].as_posix()))
+    return 0
+
+
+def register(sub, common) -> None:
+    p = sub.add_parser(
+        "projectcontextpacker", aliases=["pcp"], parents=[common],
+        help="pack a project into one AI-prompt-friendly file",
+        description="Bundle a project into a single file (directory tree + file contents)\n"
+                    "ready to paste into an AI chat. Respects .gitignore, skips binaries,\n"
+                    "lock files and huge files, and reports token counts.",
+        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: ./<name>-context.md)")
+    p.add_argument("--format", choices=["markdown", "xml"], default="markdown", help="output format")
+    p.add_argument("--max-tokens", type=int, metavar="N", help="stay under roughly N tokens")
+    p.add_argument("--max-file-kb", type=float, default=200, metavar="KB", help="skip files bigger than this (default 200)")
+    p.add_argument("--include", nargs="+", metavar="EXT", help="only these extensions, e.g. .py .md")
+    p.add_argument("--exclude", nargs="+", metavar="GLOB", help="skip paths matching these globs")
+    p.add_argument("--copy", action="store_true", help="also copy the result to the clipboard")
+    p.add_argument("--stdout", action="store_true", help="print to stdout instead of writing a file")
+    p.set_defaults(func=run)
+
+
+META = ("AI Helpers", "projectcontextpacker", "pcp", "pack a project into one AI-prompt file with token counts")