help2skill 0.1.0__py3-none-any.whl

help2skill/cli.py

@@ -0,0 +1,264 @@
+"""The ``help2skill`` command."""
+
+from __future__ import annotations
+
+import argparse
+import difflib
+import importlib
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+from . import (
+    REFERENCE_FILE,
+    SKILL_MAX_CHARS,
+    UNNAMED,
+    __version__,
+    check_skill_file,
+    find_machine_paths,
+    introspect,
+    program_name,
+    read_settings,
+    redact_home,
+    render_llms,
+    write_skill,
+)
+
+_STALE_KINDS = ("stale-block", "missing-block", "stale-reference", "missing-reference")
+
+
+class UsageError(Exception):
+    """A problem with the user's input: printed as one line, exit status 2."""
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="help2skill",
+        description="Generate LLM-ready docs and SKILL.md files from Click, Typer and argparse CLIs.",
+        epilog="TARGET is the import path of the CLI object, e.g. mypkg.cli:app. For a function "
+        "that builds an argparse parser, write mypkg.cli:build_parser() (with parentheses).",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = parser.add_subparsers(dest="action", required=True)
+
+    md = sub.add_parser("markdown", help="Print the Markdown reference for a CLI.")
+    md.add_argument("target", help="CLI object, e.g. mypkg.cli:app")
+    md.add_argument(
+        "--max-chars",
+        type=int,
+        default=0,
+        help="Print only an index when the reference is longer than this (default: 0 = no limit)",
+    )
+
+    skill = sub.add_parser("skill", help="Create a SKILL.md, or refresh its generated block.")
+    skill.add_argument("target", help="CLI object, e.g. mypkg.cli:app")
+    skill.add_argument(
+        "--name", help="Skill name: lowercase letters, digits, hyphens (needed to create the file)"
+    )
+    skill.add_argument("--description", help="Skill description (default: from the CLI help)")
+    skill.add_argument(
+        "--output",
+        "-o",
+        type=Path,
+        help="SKILL.md path (default: skills/<name>/SKILL.md)",
+    )
+    skill.add_argument(
+        "--max-chars",
+        type=int,
+        help=f"Above this size, keep an index in SKILL.md and the full reference in {REFERENCE_FILE} "
+        f"(default: {SKILL_MAX_CHARS}, or the value stored in the file; 0 = never split)",
+    )
+
+    chk = sub.add_parser("check", help="Exit 1 if a SKILL.md has drifted from the CLI.")
+    chk.add_argument("target", help="CLI object, e.g. mypkg.cli:app")
+    chk.add_argument("path", type=Path, help="SKILL.md to check")
+    chk.add_argument("--max-chars", type=int, help="Override the value stored in the file")
+    for p in (md, skill, chk):
+        p.add_argument(
+            "--program",
+            help="Program name users type (default: stored in the file, else the console script "
+            "that points at TARGET, else the CLI's own name)",
+        )
+        p.add_argument(
+            "--hide-default",
+            action="append",
+            metavar="NAME",
+            dest="hide_defaults",
+            help="Leave out the default of this parameter (name or option), e.g. one computed at "
+            "run time; repeatable. Stored in the file.",
+        )
+        p.add_argument(
+            "--app-dir",
+            metavar="DIR",
+            help="Import TARGET from this directory, e.g. src (default: the current directory)",
+        )
+        p.add_argument(
+            "--resolve",
+            metavar="MODULE:FUNC",
+            help="Function that turns a lazy placeholder command into the real command",
+        )
+    return parser
+
+
+def load_target(spec: str, *, call: bool = True, app_dir: str | None = None) -> Any:
+    """Import ``module:attr``; ``module:func()`` calls ``func`` (e.g. a parser factory)."""
+    module_name, _, attr = spec.partition(":")
+    if not module_name or not attr or "/" in module_name or module_name.endswith(".py"):
+        raise UsageError(f"target must look like module.path:attribute, got {spec!r}")
+    explicit_call = attr.endswith("()")
+    attr = attr.removesuffix("()")
+    for directory in (os.getcwd(), app_dir):
+        if directory and os.path.abspath(directory) not in sys.path:
+            sys.path.insert(0, os.path.abspath(directory))
+    # argparse names an unnamed parser after sys.argv[0]; make that detectable.
+    saved_argv = sys.argv
+    sys.argv = [UNNAMED, *sys.argv[1:]]
+    try:
+        try:
+            obj: Any = importlib.import_module(module_name)
+        except ModuleNotFoundError as exc:
+            raise UsageError(
+                f"cannot import {module_name!r}: {exc}{_src_hint(module_name, app_dir)}"
+            ) from exc
+        for part in attr.split("."):
+            if not hasattr(obj, part):
+                names = [n for n in dir(obj) if not n.startswith("_")]
+                close = difflib.get_close_matches(part, names, n=1)
+                hint = f"; did you mean {close[0]!r}?" if close else ""
+                raise UsageError(f"{module_name!r} has no attribute {attr!r}{hint}")
+            obj = getattr(obj, part)
+        if call and explicit_call:
+            obj = obj()
+        elif call and callable(obj) and not _is_cli_object(obj):
+            if "parser" not in attr.rsplit(".", 1)[-1].lower():
+                raise UsageError(
+                    f"{spec} is a function, not a Click command, Typer app or ArgumentParser. "
+                    f"If it returns a parser, write {spec}() to call it."
+                )
+            obj = obj()
+    except SystemExit as exc:
+        raise UsageError(f"importing {spec} exited (status {exc.code}); point at the CLI object") from exc
+    finally:
+        sys.argv = saved_argv
+    return obj
+
+
+def _src_hint(module_name: str, app_dir: str | None) -> str:
+    top = module_name.split(".")[0]
+    if app_dir is None and (Path("src") / top).exists():
+        return "; the package is under src/: add --app-dir src or install the project (pip install -e .)"
+    return ""
+
+
+def _is_cli_object(obj: Any) -> bool:
+    return (
+        isinstance(obj, argparse.ArgumentParser)
+        or hasattr(obj, "registered_commands")
+        or (hasattr(obj, "params") and hasattr(obj, "make_context"))
+    )
+
+
+def entry_point_name(spec: str) -> str | None:
+    """Name of the installed console script that runs ``spec`` (``module:attr``), if any."""
+    from importlib.metadata import entry_points
+
+    target = spec.removesuffix("()").replace(" ", "")
+    for ep in entry_points(group="console_scripts"):
+        if ep.value.replace(" ", "") == target:
+            return ep.name
+    return None
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        return _run(args)
+    except UsageError as exc:
+        print(f"help2skill: error: {exc}", file=sys.stderr)
+        return 2
+    except (ValueError, TypeError, FileNotFoundError) as exc:
+        print(f"help2skill: error: {exc}", file=sys.stderr)
+        return 2
+
+
+def _run(args: argparse.Namespace) -> int:
+    cli = load_target(args.target, app_dir=args.app_dir)
+    resolve = load_target(args.resolve, call=False, app_dir=args.app_dir) if args.resolve else None
+    stored = None
+    if args.action == "skill" and args.output and args.output.exists():
+        stored = read_settings(args.output.read_text(encoding="utf-8")).program
+    if args.action == "check" and args.path.exists():
+        stored = read_settings(args.path.read_text(encoding="utf-8")).program
+    program = program_name(cli, args.program, stored, entry_point_name(args.target), resolve=resolve)
+
+    if args.action == "markdown":
+        if program is None:
+            _warn_unnamed(introspect(cli, resolve=resolve).name)
+        cmd = introspect(cli, program, resolve=resolve, hide_defaults=args.hide_defaults)
+        text = redact_home(render_llms(cmd, max_chars=args.max_chars))
+        _warn_machine_paths(text, "output")
+        sys.stdout.write(text)
+        return 0
+
+    if args.action == "skill":
+        if args.output is None and not args.name:
+            raise UsageError("pass --name (to create skills/<name>/SKILL.md) or --output PATH")
+        output = args.output or Path("skills") / args.name / "SKILL.md"
+        path = write_skill(
+            cli,
+            output,
+            name=args.name,
+            description=args.description,
+            program=program,
+            max_chars=args.max_chars,
+            resolve=resolve,
+            hide_defaults=args.hide_defaults,
+        )
+        print(f"wrote {path}")
+        reference = path.parent / REFERENCE_FILE
+        if reference.exists():
+            print(f"wrote {reference}")
+        for written in (path, reference):
+            if written.exists():
+                _warn_machine_paths(written.read_text(encoding="utf-8"), str(written))
+        return 0
+
+    problems = check_skill_file(
+        cli,
+        args.path,
+        program=program,
+        max_chars=args.max_chars,
+        resolve=resolve,
+        hide_defaults=args.hide_defaults,
+    )
+    for problem in problems:
+        print(f"{args.path}: {problem}", file=sys.stderr)
+    if any(p.kind in _STALE_KINDS for p in problems):
+        print(f"help2skill: regenerate with: help2skill skill {args.target} -o {args.path}", file=sys.stderr)
+    if problems:
+        return 1
+    print(f"{args.path}: in sync with {args.target}")
+    return 0
+
+
+def _warn_unnamed(name: str) -> None:
+    shown = "the script name" if name == UNNAMED else repr(name)
+    print(
+        f"help2skill: warning: program name unknown (the CLI calls itself {shown}); "
+        "pass --program NAME or install the console script",
+        file=sys.stderr,
+    )
+
+
+def _warn_machine_paths(text: str, where: str) -> None:
+    for found in find_machine_paths(text):
+        print(
+            f"help2skill: warning: {where} contains a machine-specific path {found!r}; "
+            "review it before committing",
+            file=sys.stderr,
+        )
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

help2skill/click.py

@@ -0,0 +1,98 @@
+"""Click integration: a ``--llms`` flag that prints the Markdown reference."""
+
+from __future__ import annotations
+
+import os
+import sys
+from typing import Any
+
+# No top-level ``import click``: Typer >= 0.26 vendors Click, so a Typer app may run
+# without the ``click`` package installed.
+from ._click import from_context
+from .render import LLMS_MAX_CHARS, render_llms
+
+LLMS_HELP = "Print a Markdown reference of this command for LLM agents, then exit."
+MAX_CHARS_ENV = "HELP2SKILL_LLMS_MAX_CHARS"
+
+
+def print_llms(ctx: Any, param: Any, value: bool) -> None:
+    """Eager option callback usable with Click and Typer-built commands."""
+    if not value or ctx.resilient_parsing:
+        return
+    text = render_llms(
+        from_context(ctx), max_chars=_max_chars(), subcommand_flag=_subcommands_have_llms(ctx.command)
+    )
+    sys.stdout.write(text)
+    sys.stdout.flush()
+    ctx.exit()
+
+
+def _subcommands_have_llms(cmd: Any) -> bool:
+    subs = list((getattr(cmd, "commands", None) or {}).values())
+    return bool(subs) and all(any(getattr(p, "name", None) == "llms" for p in s.params) for s in subs)
+
+
+def _max_chars() -> int:
+    """Output budget for ``--llms``; set the env var to 0 for the full reference."""
+    try:
+        return int(os.environ.get(MAX_CHARS_ENV, LLMS_MAX_CHARS))
+    except ValueError:
+        return LLMS_MAX_CHARS
+
+
+def llms_option(*param_decls: str, **kwargs: Any):
+    """Decorator adding ``--llms`` to one Click command or group.
+
+    On a group it prints the whole subtree, so putting it on the root is enough
+    for most tools. Use :func:`add_llms_option` to add it at every level.
+    """
+    import click
+
+    kwargs.setdefault("help", LLMS_HELP)
+    return click.option(
+        *(param_decls or ("--llms",)),
+        is_flag=True,
+        expose_value=False,
+        is_eager=True,
+        callback=print_llms,
+        **kwargs,
+    )
+
+
+def add_llms_option(cmd: Any, *, recursive: bool = True) -> Any:
+    """Append ``--llms`` to an already-built command (and its subcommands).
+
+    Works for Typer-built commands too, whose classes come from Typer's
+    vendored copy of Click.
+    """
+    option_cls = _option_class(cmd)
+    for node in _iter_commands(cmd) if recursive else [cmd]:
+        if any(getattr(p, "name", None) == "llms" for p in node.params):
+            continue
+        node.params.append(
+            option_cls(
+                param_decls=["--llms"],
+                is_flag=True,
+                expose_value=False,
+                is_eager=True,
+                callback=print_llms,
+                help=LLMS_HELP,
+            )
+        )
+    return cmd
+
+
+def _option_class(cmd: Any) -> Any:
+    if type(cmd).__module__.startswith("typer"):
+        from typer.core import TyperOption
+
+        return TyperOption
+    import click
+
+    return click.Option
+
+
+def _iter_commands(cmd: Any):
+    yield cmd
+    for sub in (getattr(cmd, "commands", None) or {}).values():
+        yield from _iter_commands(sub)

help2skill/model.py

@@ -0,0 +1,89 @@
+"""Framework-neutral description of a command-line interface."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Param:
+    """One option or positional argument."""
+
+    name: str
+    kind: str  # "option" or "argument"
+    opts: list[str] = field(default_factory=list)
+    secondary_opts: list[str] = field(default_factory=list)
+    type: str = "text"
+    choices: list[str] | None = None
+    required: bool = False
+    default: str | None = None
+    is_flag: bool = False
+    multiple: bool = False
+    nargs: int | str = 1
+    envvars: list[str] = field(default_factory=list)
+    help: str | None = None
+    metavar: str | None = None
+    # One token per value slot, e.g. ["NAME", "[integer|text]"] for a 2-tuple option.
+    value_tokens: list[str] | None = None
+    count: bool = False  # -v, -vv, -vvv
+    range: str | None = None  # e.g. "1<=x<=50"
+    case_insensitive: bool = False
+    prompts: bool = False  # asks interactively when omitted
+    optional_value: bool = False  # option may be given without its value
+
+    @property
+    def is_option(self) -> bool:
+        return self.kind == "option"
+
+
+@dataclass
+class Command:
+    """A command or command group, with its full invocation path."""
+
+    name: str
+    path: list[str]
+    help: str | None = None
+    short_help: str | None = None
+    params: list[Param] = field(default_factory=list)
+    subcommands: list[Command] = field(default_factory=list)
+    deprecated: bool = False
+    # Subcommand run when the first token is not a subcommand name (click-default-group).
+    default_command: str | None = None
+    aliases: list[str] = field(default_factory=list)
+    # Names that run a command but are not documented (hidden commands).
+    hidden_subcommands: list[str] = field(default_factory=list)
+    # Groups of options that cannot be combined: (option names, one is required).
+    exclusive: list[tuple[list[str], bool]] = field(default_factory=list)
+
+    @property
+    def is_group(self) -> bool:
+        return bool(self.subcommands)
+
+    @property
+    def options(self) -> list[Param]:
+        return [p for p in self.params if p.is_option]
+
+    @property
+    def arguments(self) -> list[Param]:
+        return [p for p in self.params if not p.is_option]
+
+    def walk(self) -> Iterator[Command]:
+        """Yield this command and every descendant, depth first."""
+        yield self
+        for sub in self.subcommands:
+            yield from sub.walk()
+
+    def get(self, name: str) -> Command | None:
+        """Find a direct subcommand by name or alias."""
+        for sub in self.subcommands:
+            if sub.name == name or name in sub.aliases:
+                return sub
+        return None
+
+    def find(self, path: list[str]) -> Command | None:
+        """Resolve a list of subcommand names below this command."""
+        node: Command | None = self
+        for part in path:
+            node = node.get(part) if node else None
+        return node

help2skill/privacy.py

@@ -0,0 +1,33 @@
+"""Keep machine-specific paths out of generated files.
+
+Help text is sometimes computed at runtime (``default: /Users/alice/.cache/...``).
+Written files replace the current user's home directory with ``~``, which also keeps
+the drift check stable between a laptop and CI.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+
+_MACHINE_PATH_RE = re.compile(r"(/Users/[^/\s`'\"]+|/home/[^/\s`'\"]+|[A-Za-z]:\\Users\\[^\\\s`'\"]+)")
+
+
+def _home_variants(home: str | None) -> list[str]:
+    home = home or str(Path.home())
+    variants = {home, os.path.realpath(home)}
+    return sorted((v.rstrip("/\\") for v in variants if len(v) > 1), key=len, reverse=True)
+
+
+def redact_home(text: str, home: str | None = None) -> str:
+    """Replace the home directory (``home`` or the current user's) with ``~``."""
+    for variant in _home_variants(home):
+        # Not followed by a name character, so /home/alice does not match /home/alicex.
+        text = re.sub(re.escape(variant) + r"(?![\w-])", "~", text)
+    return text
+
+
+def find_machine_paths(text: str) -> list[str]:
+    """Return home-directory-like paths left in ``text``, e.g. another user's."""
+    return sorted(set(_MACHINE_PATH_RE.findall(text)))