kctl-lib 0.8.2__tar.gz → 0.9.0__tar.gz

{kctl_lib-0.8.2 → kctl_lib-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kctl-lib
-Version: 0.8.2
+Version: 0.9.0
 Summary: Shared core library for kctl-* CLI tools
 Requires-Python: >=3.12
 Requires-Dist: httpx>=0.28.0

{kctl_lib-0.8.2 → kctl_lib-0.9.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "kctl-lib"
-version = "0.8.2"
+version = "0.9.0"
 description = "Shared core library for kctl-* CLI tools"
 requires-python = ">=3.12"
 dependencies = [

{kctl_lib-0.8.2 → kctl_lib-0.9.0}/src/kctl_lib/__init__.py

@@ -24,13 +24,15 @@ Public API:
     - tui: Textual TUI (add_tui_command)
 """
 
-__version__ = "0.8.2"
+__version__ = "0.9.0"
 
 from kctl_lib.api_client import APIClient
 from kctl_lib.async_api_client import AsyncAPIClient
 from kctl_lib.callbacks import AppContextBase
 from kctl_lib.docker import DockerManager
 from kctl_lib.doctor_base import CheckResult, DoctorCheck, run_doctor
+from kctl_lib.dry_run import with_dry_run
+from kctl_lib.error_handler import cli_entrypoint
 from kctl_lib.exceptions import (
     APIError,
     AppNotFoundError,
@@ -43,6 +45,7 @@ from kctl_lib.exceptions import (
     NotFoundError,
     ValidationError,
 )
+from kctl_lib.introspection import dump_command_list, dump_command_tree, register_introspection_commands
 from kctl_lib.output import Output
 from kctl_lib.progress import ItemProgress, LogCollector, PerfTimer, StepResult, StepTracker
 from kctl_lib.validate import Issue
@@ -56,6 +59,7 @@ __all__ = [
     "AuthenticationError",
     "CheckResult",
     "CommandError",
+    "cli_entrypoint",
     "ConfigError",
     "ConnectionError",
     "DockerError",
@@ -71,7 +75,11 @@ __all__ = [
     "StepResult",
     "StepTracker",
     "ValidationError",
+    "dump_command_list",
+    "dump_command_tree",
+    "register_introspection_commands",
     "run_doctor",
+    "with_dry_run",
 ]
 
 

kctl_lib-0.9.0/src/kctl_lib/dry_run.py

@@ -0,0 +1,76 @@
+"""--explain dry-run support for Typer commands.
+
+Decorator that adds an --explain flag to a Typer command. When passed,
+prints the action plan and exits 0 without invoking the wrapped function.
+Useful for AI agents and humans previewing destructive operations.
+
+Usage:
+    @app.command()
+    @with_dry_run(summary="Create DNS record name={name} content={content}")
+    def create(name: str, content: str) -> None:
+        ...
+"""
+
+from __future__ import annotations
+
+import functools
+import inspect
+import typing
+from collections.abc import Callable
+from typing import Any
+
+import typer
+
+
+def with_dry_run(summary: str) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    """Decorate a Typer command so `--explain` prints the action and exits 0.
+
+    The summary string supports named placeholders matching the wrapped
+    function's parameter names (e.g. "Create domain {name} with TTL {ttl}").
+    """
+
+    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+        # Resolve forward-referenced annotations (PEP 563 / ``from __future__
+        # import annotations``) so Typer can see Annotated metadata like
+        # ``typer.Option("--type")``. Without this, annotations remain as
+        # raw strings and Typer treats every parameter as a positional
+        # argument.
+        try:
+            resolved_hints = typing.get_type_hints(func, include_extras=True)
+        except Exception:
+            resolved_hints = {}
+
+        sig = inspect.signature(func)
+        resolved_params = []
+        for name, param in sig.parameters.items():
+            if name in resolved_hints:
+                resolved_params.append(param.replace(annotation=resolved_hints[name]))
+            else:
+                resolved_params.append(param)
+        # Extend signature so Typer registers --explain as a Boolean flag
+        new_params = resolved_params + [
+            inspect.Parameter(
+                "explain",
+                inspect.Parameter.KEYWORD_ONLY,
+                default=typer.Option(False, "--explain", help="Show what would happen and exit."),
+                annotation=bool,
+            )
+        ]
+
+        @functools.wraps(func)
+        def wrapper(*args: Any, explain: bool = False, **kwargs: Any) -> Any:
+            if explain:
+                bound = sig.bind_partial(*args, **kwargs)
+                bound.apply_defaults()
+                try:
+                    rendered = summary.format(**bound.arguments)
+                except KeyError as exc:
+                    raise typer.BadParameter(f"with_dry_run summary references unknown parameter {exc}") from exc
+                typer.echo(f"[explain] {rendered}")
+                raise typer.Exit(0)
+            return func(*args, **kwargs)
+
+        wrapper.__signature__ = sig.replace(parameters=new_params)  # type: ignore[attr-defined]
+        return wrapper
+
+    return decorator

kctl_lib-0.9.0/src/kctl_lib/error_handler.py

@@ -0,0 +1,140 @@
+"""Wrap Typer apps so KctlError subclasses become user-facing messages.
+
+We translate :class:`KctlError` raised inside a command body into a clean
+one-line message (or JSON when ``--json`` is requested) instead of a Python
+traceback. Both the real CLI entry point and ``CliRunner.invoke`` end up
+calling the command's wrapped callback, so wrapping each registered command
+callback (and the root callback) is sufficient:
+
+* Production path: console script -> ``app()`` -> Typer's ``__call__`` ->
+  click -> invokes the command function (which IS wrapped).
+* Test path: ``CliRunner.invoke`` -> ``typer.main.get_command`` -> click ->
+  invokes the command function (which IS wrapped).
+
+An earlier iteration also assigned ``app.__call__ = wrapped_call`` thinking
+this would intercept ``app()``; that was a misunderstanding of Python's
+special method lookup, which goes through ``type(obj).__call__`` and ignores
+the instance dict. The instance-level assignment was dead code and has been
+removed.
+
+``cli_entrypoint`` is idempotent: wrapping the same app twice is a no-op,
+and wrapping a callback that's already wrapped is skipped.
+"""
+
+from __future__ import annotations
+
+import functools
+import json
+import sys
+from collections.abc import Callable
+from typing import Any
+
+import click
+import typer
+
+from kctl_lib.exceptions import KctlError
+
+_JSON_PARAM_NAME = "json"  # Host callbacks must name their --json parameter `json` for JSON-mode error output to work
+
+
+def _wants_json() -> bool:
+    # Assumes -j is reserved globally for --json per kctl-lib CLI convention
+    if "--json" in sys.argv or "-j" in sys.argv:
+        return True
+    # When invoked via click (incl. ``CliRunner.invoke``) ``sys.argv`` isn't
+    # rewritten, so consult the active click context. ``cli_entrypoint``
+    # registers a root callback that accepts ``--json`` for this purpose.
+    try:
+        ctx = click.get_current_context(silent=True)
+    except RuntimeError:
+        ctx = None
+    if ctx is not None:
+        params = ctx.find_root().params
+        if params.get(_JSON_PARAM_NAME):
+            return True
+    return False
+
+
+def _emit_error(exc: KctlError) -> None:
+    name = exc.__class__.__name__
+    message = str(exc)
+    if _wants_json():
+        sys.stdout.write(json.dumps({"error": name, "message": message}) + "\n")
+    else:
+        sys.stderr.write(f"❌ {name}: {message}\n")
+
+
+def _wrap_callback(callback: Callable[..., Any]) -> Callable[..., Any]:
+    """Wrap a single command/callback so KctlError -> clean message + Exit(1)."""
+
+    if getattr(callback, "_kctl_wrapped", False):
+        return callback
+
+    @functools.wraps(callback)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        try:
+            return callback(*args, **kwargs)
+        except KctlError as exc:
+            _emit_error(exc)
+            raise typer.Exit(1) from exc
+
+    wrapper._kctl_wrapped = True  # type: ignore[attr-defined]
+    return wrapper
+
+
+def cli_entrypoint(app: typer.Typer) -> typer.Typer:
+    """Wrap a Typer app so :class:`KctlError` subclasses become clean messages.
+
+    Idempotent -- wrapping the same app twice is a no-op.
+
+    ## Usage
+
+    Call ``cli_entrypoint(app)`` AFTER registering all commands and any
+    ``@app.callback()``. Calling it earlier may cause the root callback
+    installation to be overwritten by a later ``@app.callback()`` decoration.
+    """
+    if getattr(app, "_kctl_wrapped", False):
+        return app
+
+    # Wrap each registered command callback so CliRunner-based invocation
+    # (and any direct click-command invocation) also benefits from the
+    # KctlError translation.
+    for cmd_info in app.registered_commands:
+        if cmd_info.callback is not None:
+            cmd_info.callback = _wrap_callback(cmd_info.callback)
+
+    # Wrap the app callback too, if one is registered.
+    if app.registered_callback is not None and app.registered_callback.callback is not None:
+        app.registered_callback.callback = _wrap_callback(app.registered_callback.callback)
+
+    # Typer flattens single-command apps unless a callback exists, which would
+    # cause ``runner.invoke(app, ["cmd_name"])`` to be rejected as an unexpected
+    # extra argument. Register a no-op callback if none is set so the
+    # subcommand structure is preserved regardless of command count.
+    #
+    # The callback declares ``--json`` so click parses it as a root-level flag
+    # even when ``sys.argv`` isn't rewritten (e.g. under ``CliRunner.invoke``).
+    # The value is read back via :func:`_wants_json`.
+    if app.registered_callback is None:
+
+        @app.callback()
+        def _kctl_root_callback(
+            json: bool = typer.Option(  # noqa: A002 -- click param name is "json"
+                False,
+                "--json",
+                "-j",
+                help="Emit machine-readable JSON output.",
+            ),
+        ) -> None:
+            """No-op root callback installed by cli_entrypoint."""
+
+    # NOTE: We intentionally do NOT assign ``app.__call__ = ...``. Python's
+    # special method lookup bypasses the instance dict and goes through
+    # ``type(app).__call__``, so an instance-level assignment is dead code.
+    # Wrapping each command callback (and the root callback) is sufficient
+    # because both the production path (console script -> Typer.__call__ ->
+    # click -> command function) and the test path (CliRunner.invoke ->
+    # typer.main.get_command -> click -> command function) end up calling
+    # the wrapped callback.
+    app._kctl_wrapped = True  # type: ignore[attr-defined]
+    return app

kctl_lib-0.9.0/src/kctl_lib/introspection.py

@@ -0,0 +1,108 @@
+"""Machine-readable Typer command introspection for AI agents.
+
+Exposes `kctl-<x> commands tree --json` (full hierarchy) and
+`kctl-<x> commands list --json` (flat leaf paths) so an AI agent can
+discover the full command surface in one structured call instead of
+walking N `--help` invocations.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import typer
+from click import Command, Group
+
+_ROOT_NAME = "root"
+
+
+def _normalize_name(name: str) -> str:
+    """Strip Typer's trailing dash artifact from underscore-suffixed function names.
+
+    Typer converts a function named ``list_`` (used to avoid shadowing the
+    Python builtin) to a command named ``list-``. From an AI agent's
+    perspective the canonical command name is ``list``, so we drop the
+    trailing dash for non-root nodes.
+    """
+    if name != _ROOT_NAME and name.endswith("-"):
+        return name.rstrip("-")
+    return name
+
+
+def _walk_click_command(name: str, cmd: Command) -> dict[str, Any]:
+    node: dict[str, Any] = {
+        "name": _normalize_name(name),
+        "help": (cmd.help or "").strip(),
+    }
+    if isinstance(cmd, Group):
+        groups: list[dict[str, Any]] = []
+        commands: list[dict[str, Any]] = []
+        for sub_name, sub in cmd.commands.items():
+            child = _walk_click_command(sub_name, sub)
+            (groups if isinstance(sub, Group) else commands).append(child)
+        node["groups"] = groups
+        node["commands"] = commands
+    else:
+        node["params"] = [{"name": p.name, "type": getattr(p.type, "name", str(p.type))} for p in cmd.params]
+    return node
+
+
+def dump_command_tree(app: typer.Typer) -> dict[str, Any]:
+    """Return the full command hierarchy of a Typer app as a dict.
+
+    Root node always has 'groups' and 'commands' keys, even for single-command
+    apps (where the root would otherwise be a leaf Command, not a Group).
+    """
+    click_app = typer.main.get_command(app)
+    root = _walk_click_command(_ROOT_NAME, click_app)
+    root.setdefault("groups", [])
+    root.setdefault("commands", [])
+    return root
+
+
+def _flatten(node: dict[str, Any], prefix: str = "") -> list[str]:
+    paths: list[str] = []
+    name = node["name"]
+    qualified = "" if name == _ROOT_NAME else (f"{prefix} {name}".strip() if prefix else name)
+    for cmd in node.get("commands", []):
+        leaf = f"{qualified} {cmd['name']}".strip()
+        paths.append(leaf)
+    for group in node.get("groups", []):
+        paths.extend(_flatten(group, qualified))
+    return paths
+
+
+def dump_command_list(app: typer.Typer) -> list[str]:
+    """Flat list of all leaf commands as 'group verb' strings, sorted."""
+    return sorted(_flatten(dump_command_tree(app)))
+
+
+def register_introspection_commands(app: typer.Typer) -> None:
+    """Add a `commands` group to the app for AI-friendly discovery.
+
+    Idempotent: calling twice does not re-register.
+    """
+    if getattr(app, "_kctl_introspection_registered", False):
+        return
+
+    commands_app = typer.Typer(help="Machine-readable command discovery (for AI agents).")
+
+    @commands_app.command("tree")
+    def tree_cmd() -> None:
+        """Dump the full command tree as JSON."""
+        payload = dump_command_tree(app)
+        typer.echo(json.dumps(payload, indent=2))
+
+    @commands_app.command("list")
+    def list_cmd(json_flag: bool = typer.Option(True, "--json/--no-json")) -> None:
+        """List all leaf commands as 'group verb' strings."""
+        paths = dump_command_list(app)
+        if json_flag:
+            typer.echo(json.dumps(paths))
+        else:
+            for p in paths:
+                typer.echo(p)
+
+    app.add_typer(commands_app, name="commands")
+    app._kctl_introspection_registered = True  # type: ignore[attr-defined]

{kctl_lib-0.8.2 → kctl_lib-0.9.0}/src/kctl_lib/skill_generator.py

@@ -245,13 +245,24 @@ def generate_skill(
 
     lines: list[str] = []
 
+    # Slim frontmatter description (<= 200 chars). The full trigger keyword
+    # list now lives in the body ## Triggers section to keep the per-session
+    # token cost of loading all skills into Claude's picker low.
+    short_description = (
+        f"{description} ({len(groups)} groups, ~{total_commands} commands). "
+        f"MUST use for ANY {cli_name} operation. "
+        f"See SKILL.md ## Triggers for keywords."
+    )
+    if len(short_description) > 200:
+        raise ValueError(
+            f"SKILL.md description must be <=200 chars, got {len(short_description)}: {short_description!r}"
+        )
+
     # Frontmatter
     lines.append("---")
     lines.append(f"name: {skill_name}")
     lines.append("description: >")
-    lines.append(f"  {description} ({len(groups)} groups, ~{total_commands} commands).")
-    lines.append(f"  MUST use for ANY {cli_name} operation.")
-    lines.append(f"  Triggers on: {triggers}.")
+    lines.append(f"  {short_description}")
     lines.append(f"  Auto-generated: {datetime.now(UTC).strftime('%Y-%m-%d')}")
     lines.append(f"  registry_hash: {registry_hash}")
     lines.append("---")
@@ -287,6 +298,15 @@ def generate_skill(
     lines.append("| `--version`, `-V` | Show version |")
     lines.append("")
 
+    # Triggers — full keyword list moved out of frontmatter so the skill
+    # picker only loads the slim description by default.
+    lines.append("## Triggers")
+    lines.append("")
+    lines.append("Auto-invoke this skill when the user references any of these keywords:")
+    lines.append("")
+    lines.append(triggers)
+    lines.append("")
+
     # Command reference
     lines.append("## Command Reference")
     lines.append("")

kctl_lib-0.9.0/tests/test_dry_run.py

@@ -0,0 +1,76 @@
+"""Tests for with_dry_run decorator."""
+
+from __future__ import annotations
+
+import typer
+from typer.testing import CliRunner
+
+from kctl_lib.dry_run import with_dry_run
+
+SIDE_EFFECT: list[str] = []
+
+
+def _build_app() -> typer.Typer:
+    app = typer.Typer()
+    SIDE_EFFECT.clear()
+
+    # Callback forces Typer to treat the app as a command group even though
+    # only one subcommand is registered. Without it, Typer collapses a
+    # single-command app and the leading "create" arg gets consumed as a name.
+    @app.callback()
+    def _main() -> None:
+        pass
+
+    @app.command()
+    @with_dry_run(summary="Create domain {name} with TTL {ttl}")
+    def create(name: str, ttl: int = 3600) -> None:
+        SIDE_EFFECT.append(f"created:{name}:{ttl}")
+
+    return app
+
+
+def test_explain_prints_plan_and_skips_execution() -> None:
+    runner = CliRunner()
+    app = _build_app()
+    result = runner.invoke(app, ["create", "example.com", "--ttl", "60", "--explain"])
+    assert result.exit_code == 0
+    assert "Create domain example.com with TTL 60" in result.output
+    assert SIDE_EFFECT == []
+
+
+def test_without_explain_runs_normally() -> None:
+    runner = CliRunner()
+    app = _build_app()
+    result = runner.invoke(app, ["create", "example.com", "--ttl", "60"])
+    assert result.exit_code == 0
+    assert SIDE_EFFECT == ["created:example.com:60"]
+
+
+def test_explain_uses_default_value() -> None:
+    runner = CliRunner()
+    app = _build_app()
+    result = runner.invoke(app, ["create", "example.com", "--explain"])
+    assert result.exit_code == 0
+    assert "Create domain example.com with TTL 3600" in result.output
+    assert SIDE_EFFECT == []
+
+
+def test_summary_with_bad_placeholder_raises_clean_error() -> None:
+    runner = CliRunner()
+
+    app = typer.Typer()
+
+    @app.callback()
+    def _root() -> None:
+        pass
+
+    @app.command()
+    @with_dry_run(summary="Reference {nonexistent_param}")
+    def create(name: str) -> None:
+        pass
+
+    result = runner.invoke(app, ["create", "example.com", "--explain"])
+    assert result.exit_code != 0
+    # typer.BadParameter renders something like:
+    # "Invalid value: with_dry_run summary references unknown parameter 'nonexistent_param'"
+    assert "nonexistent_param" in result.output

kctl_lib-0.9.0/tests/test_error_handler.py

@@ -0,0 +1,129 @@
+"""Tests for cli_entrypoint error wrapping."""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+import typer
+from typer.testing import CliRunner
+
+from kctl_lib.error_handler import cli_entrypoint
+from kctl_lib.exceptions import (
+    APIError,
+    AuthenticationError,
+    ConfigError,
+)
+from kctl_lib.exceptions import (
+    ConnectionError as KctlConnectionError,
+)
+
+
+def _make_app(raise_exc: Exception) -> typer.Typer:
+    app = typer.Typer()
+
+    @app.command()
+    def go() -> None:
+        raise raise_exc
+
+    return cli_entrypoint(app)
+
+
+# click >= 8.3 removed the `mix_stderr` kwarg and now always separates stderr by
+# default, which is the behavior the tests require. We construct CliRunner via a
+# helper that passes `mix_stderr=False` only on older click versions.
+def _runner() -> CliRunner:
+    try:
+        return CliRunner(mix_stderr=False)  # type: ignore[call-arg]
+    except TypeError:
+        return CliRunner()
+
+
+class TestConfigError:
+    def test_pretty_message(self) -> None:
+        runner = _runner()
+        app = _make_app(ConfigError("missing profile"))
+        result = runner.invoke(app, ["go"])
+        assert result.exit_code == 1
+        assert "missing profile" in result.stderr
+        assert "Traceback" not in result.stderr
+
+    def test_json_mode(self) -> None:
+        runner = _runner()
+        app = _make_app(ConfigError("missing profile"))
+        result = runner.invoke(app, ["--json", "go"])
+        assert result.exit_code == 1
+        payload = json.loads(result.stdout)
+        assert payload == {
+            "error": "ConfigError",
+            "message": "missing profile",
+        }
+
+
+class TestOtherExceptions:
+    @pytest.mark.parametrize(
+        "exc,fragment",
+        [
+            (AuthenticationError("bad token"), "AuthenticationError"),
+            (KctlConnectionError("api.example.com", ValueError("timeout")), "ConnectionError"),
+            (APIError("rate limited"), "APIError"),
+        ],
+    )
+    def test_known_errors_become_clean_messages(self, exc, fragment) -> None:
+        runner = _runner()
+        app = _make_app(exc)
+        result = runner.invoke(app, ["go"])
+        assert result.exit_code == 1
+        assert fragment in result.stderr
+        assert "Traceback" not in result.stderr
+
+
+class TestUnknownException:
+    def test_unknown_exception_propagates(self) -> None:
+        runner = _runner()
+        app = _make_app(RuntimeError("surprise"))
+        result = runner.invoke(app, ["go"])
+        assert result.exit_code != 0
+
+
+class TestRootCallbackError:
+    def test_kctl_error_from_root_callback_is_caught(self) -> None:
+        from kctl_lib.error_handler import cli_entrypoint
+        from kctl_lib.exceptions import ConfigError
+
+        app = typer.Typer()
+
+        @app.callback()
+        def main() -> None:
+            raise ConfigError("bad root config")
+
+        @app.command()
+        def noop() -> None:
+            pass
+
+        wrapped = cli_entrypoint(app)
+        runner = _runner()
+        result = runner.invoke(wrapped, ["noop"])
+        assert result.exit_code == 1
+        assert "bad root config" in result.stderr
+        assert "Traceback" not in result.stderr
+
+
+class TestIdempotent:
+    def test_wrapping_twice_is_noop(self) -> None:
+        from kctl_lib.error_handler import cli_entrypoint
+        from kctl_lib.exceptions import ConfigError
+
+        app = typer.Typer()
+
+        @app.command()
+        def go() -> None:
+            raise ConfigError("x")
+
+        wrapped_once = cli_entrypoint(app)
+        wrapped_twice = cli_entrypoint(wrapped_once)
+        assert wrapped_once is wrapped_twice
+
+        # Callback should not be double-wrapped
+        cb = app.registered_commands[0].callback
+        assert getattr(cb, "_kctl_wrapped", False) is True

kctl_lib-0.9.0/tests/test_introspection.py

@@ -0,0 +1,117 @@
+"""Tests for introspection helpers."""
+
+from __future__ import annotations
+
+import json
+
+import typer
+from typer.testing import CliRunner
+
+from kctl_lib.introspection import (
+    _normalize_name,
+    dump_command_list,
+    dump_command_tree,
+    register_introspection_commands,
+)
+
+
+def _sample_app() -> typer.Typer:
+    app = typer.Typer(help="Sample app")
+    domains = typer.Typer(help="Manage domains")
+    app.add_typer(domains, name="domains")
+
+    @domains.command()
+    def list_(active: bool = False) -> None:
+        """List domains."""
+
+    @app.command()
+    def health() -> None:
+        """Check health."""
+
+    return app
+
+
+class TestDumpCommandTree:
+    def test_shape(self) -> None:
+        tree = dump_command_tree(_sample_app())
+        assert tree["name"] == "root"
+        groups = {g["name"]: g for g in tree["groups"]}
+        assert "domains" in groups
+        commands = {c["name"] for c in groups["domains"]["commands"]}
+        assert commands == {"list"}
+
+    def test_includes_top_level_commands(self) -> None:
+        tree = dump_command_tree(_sample_app())
+        top_commands = {c["name"] for c in tree["commands"]}
+        assert "health" in top_commands
+
+
+class TestDumpCommandTreeSingleCommand:
+    def test_single_command_app_has_groups_and_commands_keys(self) -> None:
+        app = typer.Typer()
+
+        @app.command()
+        def only() -> None:
+            """The only command."""
+
+        tree = dump_command_tree(app)
+        assert "groups" in tree
+        assert "commands" in tree
+        assert tree["groups"] == []
+        # Single-command apps may flatten the command into root params,
+        # so don't assert on commands contents — just that the key exists.
+
+
+class TestNormalizeName:
+    def test_strips_trailing_dash(self) -> None:
+        assert _normalize_name("list-") == "list"
+
+    def test_preserves_clean_name(self) -> None:
+        assert _normalize_name("list") == "list"
+
+    def test_preserves_root(self) -> None:
+        assert _normalize_name("root") == "root"
+
+    def test_preserves_internal_dashes(self) -> None:
+        assert _normalize_name("sync-jobs") == "sync-jobs"
+
+
+class TestNestedGroups:
+    def test_three_level_nesting(self) -> None:
+        app = typer.Typer()
+        outer = typer.Typer()
+        inner = typer.Typer()
+        outer.add_typer(inner, name="sequence")
+        app.add_typer(outer, name="intercompany")
+
+        @inner.command()
+        def validate() -> None: ...
+
+        paths = dump_command_list(app)
+        assert "intercompany sequence validate" in paths
+
+
+class TestDumpCommandList:
+    def test_flat_paths(self) -> None:
+        paths = dump_command_list(_sample_app())
+        assert "domains list" in paths
+        assert "health" in paths
+
+
+class TestRegister:
+    def test_commands_tree_json(self) -> None:
+        app = _sample_app()
+        register_introspection_commands(app)
+        result = CliRunner().invoke(app, ["commands", "tree"])
+        assert result.exit_code == 0
+        payload = json.loads(result.stdout)
+        assert any(g["name"] == "domains" for g in payload["groups"])
+
+    def test_commands_list_json(self) -> None:
+        app = _sample_app()
+        register_introspection_commands(app)
+        result = CliRunner().invoke(app, ["commands", "list", "--json"])
+        assert result.exit_code == 0
+        payload = json.loads(result.stdout)
+        assert "domains list" in payload
+        assert "health" in payload

{kctl_lib-0.8.2 → kctl_lib-0.9.0}/tests/test_skill_generator.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 from pathlib import Path
 
+import pytest
 import typer
 
 from kctl_lib.skill_generator import check_stale, generate_skill
@@ -45,7 +46,8 @@ class TestGenerateSkill:
         content = generate_skill(app, "kctl-test", "test-admin", "Test CLI admin")
         assert content.startswith("---")
         assert "name: test-admin" in content
-        assert "Triggers on:" in content
+        # Triggers now live in the body ## Triggers section, not frontmatter
+        assert "## Triggers" in content
 
     def test_writes_file(self, tmp_path: Path) -> None:
         app = _make_test_app()
@@ -143,7 +145,10 @@ class TestDomainTriggers:
         app = _make_test_app()
         content = generate_skill(app, "kctl-test", "test-admin", "Test")
         # "cmd1" is >3 chars and not in skip list, so should be a trigger
-        assert '"cmd1"' in content
+        # Triggers now live in the body ## Triggers section
+        body = content.split("---", 2)[2]
+        triggers_section = body.split("## Triggers", 1)[1]
+        assert "cmd1" in triggers_section
 
     def test_generic_subcommands_skipped(self) -> None:
         app = typer.Typer(name="kctl-test", help="Test")
@@ -159,7 +164,104 @@ class TestDomainTriggers:
 
         app.add_typer(sub, name="items")
         content = generate_skill(app, "kctl-test", "test-admin", "Test")
-        # Generic names like "list" and "get" should NOT be triggers
-        triggers_line = [line for line in content.splitlines() if "Triggers on:" in line][0]
-        assert '"list"' not in triggers_line
-        assert '"get"' not in triggers_line
+        # Generic names like "list" and "get" should NOT be triggers.
+        # Triggers now live in the body ## Triggers section.
+        body = content.split("---", 2)[2]
+        triggers_section = body.split("## Triggers", 1)[1].split("\n##", 1)[0]
+        assert '"list"' not in triggers_section
+        assert '"get"' not in triggers_section
+
+
+class TestSlimFrontmatter:
+    def test_description_capped_at_200_chars(self) -> None:
+        # Build a Typer app with many command groups -> many triggers
+        app = typer.Typer()
+        for name in ("alpha", "beta", "gamma", "delta", "epsilon", "zeta", "eta", "theta"):
+            sub = typer.Typer()
+            for verb in ("list", "get", "create", "update", "delete"):
+
+                @sub.command(verb)
+                def _impl() -> None: ...
+
+            app.add_typer(sub, name=name)
+
+        skill_md = generate_skill(app, "kctl-sample", "sample-admin", "Sample CLI admin")
+        # Extract description: line(s) from frontmatter. The frontmatter uses
+        # `description: >` folded scalar style, so collect the indented
+        # continuation lines until we reach a non-indented key or end of block.
+        first_block = skill_md.split("---", 2)[1]
+        desc_lines: list[str] = []
+        in_desc = False
+        for line in first_block.splitlines():
+            if line.startswith("description:"):
+                in_desc = True
+                # capture inline value after "description:" if any
+                inline = line.removeprefix("description:").strip()
+                if inline and inline != ">":
+                    desc_lines.append(inline.strip("\"'"))
+                continue
+            if in_desc:
+                # folded scalar continuation lines are indented
+                if line.startswith((" ", "\t")):
+                    desc_lines.append(line.strip())
+                else:
+                    break
+        assert desc_lines, "description: not found in frontmatter"
+        # Folded scalar joins with spaces
+        desc = " ".join(desc_lines).strip()
+        assert len(desc) <= 200, f"description too long: {len(desc)} chars: {desc!r}"
+
+    def test_triggers_section_in_body(self) -> None:
+        app = typer.Typer()
+        sub = typer.Typer()
+
+        @sub.command("list")
+        def _list() -> None: ...
+
+        app.add_typer(sub, name="domains")
+        skill_md = generate_skill(app, "kctl-sample", "sample-admin", "Sample CLI admin")
+        assert "## Triggers" in skill_md
+        # Triggers section appears AFTER frontmatter close, in the body
+        body = skill_md.split("---", 2)[2]
+        assert "## Triggers" in body
+        triggers_section = body.split("## Triggers", 1)[1]
+        # Group name 'domains' should appear in the triggers list
+        assert "domains" in triggers_section
+
+    def test_frontmatter_does_not_contain_full_trigger_list(self) -> None:
+        # The frontmatter should NOT include the full trigger keyword list
+        # to keep the description short (<=200 chars).
+        app = typer.Typer()
+        for name in ("alpha", "beta", "gamma", "delta", "epsilon"):
+            sub = typer.Typer()
+
+            @sub.command("audit")
+            def _audit() -> None: ...
+
+            app.add_typer(sub, name=name)
+
+        skill_md = generate_skill(app, "kctl-sample", "sample-admin", "Sample CLI admin")
+        first_block = skill_md.split("---", 2)[1]
+        # The literal full trigger phrase should not appear in frontmatter
+        assert "Triggers on:" not in first_block
+
+
+class TestDescriptionCap:
+    def test_oversize_description_raises_value_error(self) -> None:
+        """Cap must be runtime-enforced (not just an assert that PYTHONOPTIMIZE strips)."""
+        # Build an app whose generated description would exceed 200 chars.
+        # We force this by passing a long `description` parameter directly
+        # (the template substitutes it into the frontmatter line).
+        app = typer.Typer()
+
+        @app.command()
+        def noop() -> None: ...
+
+        long_desc = "X" * 500  # ensures total > 200 regardless of other content
+        with pytest.raises(ValueError, match="must be <=200 chars"):
+            generate_skill(
+                typer_app=app,
+                cli_name="kctl-overflow",
+                skill_name="overflow-admin",
+                description=long_desc,
+            )