kctl-skill 0.2.0__py3-none-any.whl

kctl_skill/__init__.py

@@ -0,0 +1,5 @@
+"""kctl-skill: author, lint, build, and install Kodemeio agent skills."""
+
+from __future__ import annotations
+
+__version__ = "0.2.0"

kctl_skill/cli.py

@@ -0,0 +1,184 @@
+from __future__ import annotations
+
+import json as _json
+from dataclasses import asdict as _asdict
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from kctl_lib import cli_entrypoint, register_introspection_commands
+
+from . import __version__
+from .discovery import discover_skills, find_repo_root
+from .generate import build_skill
+from .install import KIND_LINK, KIND_OK, KIND_REMOVE_COPY, KIND_SKIP_FOREIGN, apply_links, plan_links
+from .lint import has_errors, lint_all
+from .model import TIER_DOMAIN, TIER_TOOL
+from .scaffold import scaffold_skill
+
+app = typer.Typer(
+    name="kctl-skill",
+    help="Author, lint, build, and install Kodemeio agent skills.",
+    no_args_is_help=True,
+)
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"kctl-skill {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: bool = typer.Option(
+        False,
+        "--version",
+        "-V",
+        callback=_version_callback,
+        is_eager=True,
+        help="Show version and exit.",
+    ),
+) -> None:
+    """kctl-skill CLI."""
+
+
+@app.command("lint")
+def lint_cmd(
+    names: Annotated[list[str] | None, typer.Argument(help="Skill names to lint. Omit for all.")] = None,
+    json_out: Annotated[bool, typer.Option("--json", help="Emit JSON.")] = False,
+    warnings_as_errors: Annotated[bool, typer.Option("--warnings-as-errors", help="Exit 1 on warnings too.")] = False,
+) -> None:
+    """Lint skills against the SKILL-* rule family."""
+    root = find_repo_root()
+    wanted = list(names) if names else None
+    findings = lint_all(root, names=wanted)
+
+    if json_out:
+        typer.echo(_json.dumps({"findings": [_asdict(f) for f in findings]}, indent=2))
+    else:
+        for f in findings:
+            typer.echo(f"{f.severity:<5} {f.rule_id}  {f.location} — {f.detail}")
+        errors = sum(1 for f in findings if f.severity == "error")
+        warns = len(findings) - errors
+        count = len(discover_skills(root)) if wanted is None else len(wanted)
+        typer.echo(f"\n{errors} error(s), {warns} warning(s) across {count} skill(s)")
+
+    if has_errors(findings) or (warnings_as_errors and findings):
+        raise typer.Exit(code=1)
+
+
+@app.command("new")
+def new_cmd(
+    name: Annotated[str, typer.Argument(help="Skill name (lowercase, hyphens).")],
+    cli: Annotated[str, typer.Option("--cli", help="Console script to introspect. Implies tool tier.")] = "",
+) -> None:
+    """Scaffold a new skill directory."""
+    root = find_repo_root()
+    tier = TIER_TOOL if cli else TIER_DOMAIN
+    path = scaffold_skill(root, name, cli or None, tier)
+    typer.echo(f"created {path.relative_to(root).as_posix()} ({tier} tier)")
+    typer.echo("next: fill the TODO sections, then run `kctl-skill lint`")
+
+
+@app.command("build")
+def build_cmd(
+    names: Annotated[list[str] | None, typer.Argument(help="Skill names to build. Omit for all.")] = None,
+) -> None:
+    """Regenerate references/ for tool-tier skills from live CLI introspection."""
+    root = find_repo_root()
+    wanted = set(names) if names else None
+    total = 0
+    for ctx in discover_skills(root):
+        if wanted is not None and ctx.name not in wanted:
+            continue
+        written = build_skill(ctx)
+        if written:
+            typer.echo(f"{ctx.name}: {len(written)} reference file(s)")
+            total += len(written)
+    typer.echo(f"\n{total} reference file(s) written")
+
+
+@app.command("list")
+def list_cmd() -> None:
+    """List every skill with its tier, CLI binding, and reference count."""
+    root = find_repo_root()
+    skills = discover_skills(root)
+    for ctx in skills:
+        refs = len(list(ctx.references_dir().glob("*.md"))) if ctx.references_dir().is_dir() else 0
+        evals = len(list(ctx.evals_dir().glob("*.json"))) if ctx.evals_dir().is_dir() else 0
+        cli = ctx.config.cli or "-"
+        typer.echo(f"{ctx.name:<28} {ctx.config.tier:<7} {cli:<16} refs={refs:<3} evals={evals}")
+    typer.echo(f"\n{len(skills)} skill(s)")
+
+
+@app.command("doctor")
+def doctor_cmd(
+    home: Annotated[str, typer.Option("--home", help="Override the home directory (testing).")] = "",
+) -> None:
+    """Diagnose the skills tree and its installation: drift, staleness, and broken links."""
+    root = find_repo_root()
+    home_path = Path(home) if home else Path.home()
+    skills = discover_skills(root)
+
+    typer.echo(f"repo root:  {root}")
+    typer.echo(f"skills:     {len(skills)}")
+
+    tool = [c for c in skills if c.config.tier == TIER_TOOL]
+    typer.echo(f"tool tier:  {len(tool)}   domain tier: {len(skills) - len(tool)}")
+
+    findings = lint_all(root)
+    errors = sum(1 for f in findings if f.severity == "error")
+    stale = sum(1 for f in findings if f.rule_id == "SKILL-060")
+    typer.echo(f"lint:       {errors} error(s), {len(findings) - errors} warning(s)")
+    typer.echo(f"stale refs: {stale} (run `kctl-skill build` to refresh)")
+
+    # clean=False makes this read-only: no action can remove anything.
+    actions = plan_links(root, home_path, clean=False)
+    linked = sum(1 for a in actions if a.kind == KIND_OK)
+    missing = sum(1 for a in actions if a.kind == KIND_LINK)
+    foreign = sum(1 for a in actions if a.kind == KIND_SKIP_FOREIGN)
+    typer.echo(f"install:    {linked} linked, {missing} not linked, {foreign} blocked by a foreign path")
+    if foreign:
+        typer.echo("            run `kctl-skill link --clean` to replace stale copies")
+
+    if errors:
+        raise typer.Exit(code=1)
+
+
+@app.command("link")
+def link_cmd(
+    clean: Annotated[bool, typer.Option("--clean", help="Replace stale copied directories with symlinks.")] = False,
+    dry_run: Annotated[bool, typer.Option("--dry-run", help="Print the plan and exit without changes.")] = False,
+    yes: Annotated[bool, typer.Option("--yes", help="Skip the confirmation prompt for --clean removals.")] = False,
+    home: Annotated[str, typer.Option("--home", help="Override the home directory (testing).")] = "",
+) -> None:
+    """Symlink this repo's skills into ~/.agents/skills and ~/.claude/skills."""
+    root = find_repo_root()
+    home_path = Path(home) if home else Path.home()
+    actions = plan_links(root, home_path, clean=clean)
+
+    for action in actions:
+        typer.echo(f"{action.kind:<13} {action.path} — {action.reason}")
+
+    if dry_run:
+        typer.echo("\ndry run — nothing changed")
+        return
+
+    removals = [a for a in actions if a.kind == KIND_REMOVE_COPY]
+    if removals and not yes:
+        typer.echo(f"\n{len(removals)} directory/ies will be DELETED and replaced by symlinks:")
+        for a in removals:
+            typer.echo(f"  {a.path}")
+        typer.confirm("Proceed?", abort=True)
+
+    changed = apply_links(actions)
+    typer.echo(f"\n{changed} change(s) applied")
+
+
+# Later tasks append new commands/groups above this line.
+# register_introspection_commands and cli_entrypoint must remain the last two
+# statements in this module -- introspection needs every command registered
+# first, and cli_entrypoint wraps the fully-assembled app for error handling.
+register_introspection_commands(app)
+app = cli_entrypoint(app)

kctl_skill/core/__init__.py

@@ -0,0 +1 @@
+from __future__ import annotations

kctl_skill/core/callbacks.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from kctl_lib import AppContextBase
+
+
+@dataclass
+class AppContext(AppContextBase):
+    """Typer context for kctl-skill. Inherits lazy Output init from the base."""

kctl_skill/core/config.py

@@ -0,0 +1,19 @@
+"""Workspace root resolution for the skills toolchain."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .exceptions import SkillError
+
+_WORKSPACE_MARKER = "[tool.uv.workspace]"
+
+
+def find_repo_root(start: Path | None = None) -> Path:
+    """Walk upward until a pyproject.toml declaring [tool.uv.workspace] is found."""
+    current = (start or Path.cwd()).resolve()
+    for candidate in (current, *current.parents):
+        pyproject = candidate / "pyproject.toml"
+        if pyproject.is_file() and _WORKSPACE_MARKER in pyproject.read_text(encoding="utf-8"):
+            return candidate
+    raise SkillError(f"no uv workspace root found from {current}")

kctl_skill/core/exceptions.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from kctl_lib import KctlError
+
+
+class SkillError(KctlError):
+    """Raised when a skill directory or its configuration is unusable."""

kctl_skill/discovery.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+
+from .core.config import find_repo_root
+from .core.exceptions import SkillError
+from .model import TIER_DOMAIN, SkillConfig, SkillCtx
+
+# Re-exported so callers can pull discovery + root resolution from one module.
+__all__ = ["discover_skills", "find_repo_root", "load_skill_config"]
+
+
+def load_skill_config(path: Path) -> SkillConfig:
+    """Parse a skill.toml. Raises SkillError with an actionable message on failure."""
+    if not path.is_file():
+        raise SkillError(f"skill.toml not found at {path}")
+    try:
+        data = tomllib.loads(path.read_text(encoding="utf-8"))
+    except tomllib.TOMLDecodeError as exc:
+        raise SkillError(f"invalid TOML in {path}: {exc}") from exc
+    except OSError as exc:
+        raise SkillError(f"cannot read {path}: {exc}") from exc
+
+    raw_refs = data.get("references", {})
+    references: dict[str, list[str]] = {}
+    if isinstance(raw_refs, dict):
+        for cluster, groups in raw_refs.items():
+            if isinstance(groups, list):
+                references[str(cluster)] = [str(g) for g in groups]
+
+    cli = data.get("cli")
+    return SkillConfig(
+        tier=str(data.get("tier", TIER_DOMAIN)),
+        cli=str(cli) if cli else None,
+        references=references,
+    )
+
+
+def discover_skills(root: Path) -> list[SkillCtx]:
+    """Return every skill under <root>/skills/, sorted by name.
+
+    A directory is a skill if it contains SKILL.md. A missing skill.toml is
+    treated as a domain-tier skill with no generated references, so a
+    hand-written skill works before the sidecar is added.
+    """
+    skills_dir = root / "skills"
+    if not skills_dir.is_dir():
+        return []
+    out: list[SkillCtx] = []
+    for d in sorted(p for p in skills_dir.iterdir() if p.is_dir()):
+        if not (d / "SKILL.md").is_file():
+            continue
+        toml_path = d / "skill.toml"
+        config = load_skill_config(toml_path) if toml_path.is_file() else SkillConfig()
+        out.append(SkillCtx(name=d.name, path=d, config=config))
+    return out

kctl_skill/generate.py

@@ -0,0 +1,153 @@
+"""Generate a tool-tier skill's references/ from live Typer introspection.
+
+This module never writes SKILL.md. Routers are hand-authored; only the command
+surface is generated. That separation is what makes hand-written prose
+structurally impossible to clobber on a rebuild.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import importlib
+from pathlib import Path
+from typing import Any
+
+import typer
+from kctl_lib.introspection import dump_command_tree
+
+from .core.exceptions import SkillError
+from .model import TIER_TOOL, SkillCtx
+
+HASH_MARKER = "registry_hash:"
+_TOC_THRESHOLD = 100
+
+
+def load_cli_app(cli_name: str) -> typer.Typer:
+    """Import a console-script name's Typer app: 'kctl-odoo' -> kctl_odoo.cli:app."""
+    module_name = f"{cli_name.replace('-', '_')}.cli"
+    try:
+        module = importlib.import_module(module_name)
+    except ImportError as exc:
+        raise SkillError(f"cannot import {module_name} for CLI {cli_name!r}: {exc}") from exc
+    app = getattr(module, "app", None)
+    if not isinstance(app, typer.Typer):
+        raise SkillError(f"{module_name} does not export a Typer `app` attribute")
+    return app
+
+
+def command_tree_for_cli(cli_name: str) -> dict[str, Any]:
+    return dump_command_tree(load_cli_app(cli_name))
+
+
+def group_names_for_cli(cli_name: str) -> list[str]:
+    """Top-level command group names, sorted. Root-level leaf commands are excluded."""
+    tree = command_tree_for_cli(cli_name)
+    return sorted(g["name"] for g in tree.get("groups", []))
+
+
+def registry_hash(tree: dict[str, Any]) -> str:
+    """12-char digest over every group's name and leaf count — the staleness signal."""
+    parts: list[str] = []
+    for group in tree.get("groups", []):
+        leaves = len(group.get("commands", [])) + len(group.get("groups", []))
+        parts.append(f"{group['name']}:{leaves}")
+    raw = "|".join(sorted(parts))
+    return hashlib.sha256(raw.encode("utf-8")).hexdigest()[:12]
+
+
+def registry_hash_for_cli(cli_name: str) -> str:
+    return registry_hash(command_tree_for_cli(cli_name))
+
+
+def _flag_summary(params: list[dict[str, Any]]) -> str:
+    """Render a compact `<arg> [--opt]` signature from a command's param schema."""
+    parts: list[str] = []
+    for p in params:
+        if p.get("param_type") == "argument":
+            parts.append(f"<{p['name']}>")
+        else:
+            opt = next((o for o in p.get("opts", []) if o.startswith("--")), None)
+            if opt:
+                parts.append(opt if p.get("required") else f"[{opt}]")
+    return " ".join(parts)
+
+
+def _first_sentence(text: str) -> str:
+    first = text.strip().split("\n\n")[0].replace("\n", " ").strip()
+    for marker in ("Examples:", "Example:"):
+        if marker in first:
+            first = first[: first.index(marker)].strip()
+    return first
+
+
+def _render_group(cli_name: str, group: dict[str, Any], lines: list[str]) -> None:
+    lines.append(f"### `{cli_name} {group['name']}`")
+    lines.append("")
+    if group.get("help"):
+        lines.append(_first_sentence(group["help"]))
+        lines.append("")
+    commands = group.get("commands", [])
+    if commands:
+        lines.append("| Command | Description |")
+        lines.append("|---------|-------------|")
+        for cmd in commands:
+            sig = _flag_summary(cmd.get("params", []))
+            path = f"{group['name']} {cmd['name']}" + (f" {sig}" if sig else "")
+            lines.append(f"| `{path}` | {_first_sentence(cmd.get('help', ''))} |")
+        lines.append("")
+    for sub in group.get("groups", []):
+        _render_group(cli_name, {**sub, "name": f"{group['name']} {sub['name']}"}, lines)
+
+
+def render_reference(cli_name: str, cluster: str, groups: list[dict[str, Any]], hash_: str) -> str:
+    """Render one reference file for a cluster of command groups."""
+    body: list[str] = []
+    for group in groups:
+        _render_group(cli_name, group, body)
+
+    header = [
+        f"<!-- generated by `kctl-skill build` — do not edit. {HASH_MARKER} {hash_} -->",
+        "",
+        f"# {cli_name} — {cluster}",
+        "",
+        f"Discover exact flags before invoking: `{cli_name} commands tree --filter <group> --json`",
+        "",
+    ]
+
+    toc = ["## Contents", ""]
+    toc.extend(f"- `{cli_name} {g['name']}` — {_first_sentence(g.get('help', '')) or 'commands'}" for g in groups)
+    toc.append("")
+
+    # SKILL-012 measures the FINAL file, so the threshold has to be applied to
+    # the rendered length including header and ToC — not to `body` alone.
+    if len(header) + len(toc) + len(body) > _TOC_THRESHOLD:
+        header.extend(toc)
+
+    return "\n".join(header + body).rstrip() + "\n"
+
+
+def build_skill(ctx: SkillCtx) -> list[Path]:
+    """Regenerate every references/<cluster>.md for a tool-tier skill.
+
+    Domain-tier skills own their references by hand and are skipped.
+    Returns the list of files written.
+    """
+    if ctx.config.tier != TIER_TOOL or not ctx.config.cli:
+        return []
+
+    tree = command_tree_for_cli(ctx.config.cli)
+    hash_ = registry_hash(tree)
+    by_name = {g["name"]: g for g in tree.get("groups", [])}
+
+    refs_dir = ctx.references_dir()
+    refs_dir.mkdir(parents=True, exist_ok=True)
+
+    written: list[Path] = []
+    for cluster, group_names in sorted(ctx.config.references.items()):
+        groups = [by_name[n] for n in group_names if n in by_name]
+        if not groups:
+            continue
+        target = refs_dir / f"{cluster}.md"
+        target.write_text(render_reference(ctx.config.cli, cluster, groups, hash_), encoding="utf-8")
+        written.append(target)
+    return written

kctl_skill/install.py

@@ -0,0 +1,96 @@
+"""Symlink this repo's skills into the agent skill directories.
+
+Symlinks rather than copies: the link IS the repo file, so the three-way drift
+that copy-install produced becomes structurally impossible.
+
+Safety contract — this module deletes directories, so the rules are narrow:
+
+1. Only paths whose basename exactly matches a discovered skill name are ever
+   considered. Unrelated skills in the destination are never even inspected.
+2. A real directory is removed only under ``clean``.
+3. A symlink already pointing into this repo is ours, and is relinked freely.
+4. A symlink pointing anywhere else is never touched — reported as skip-foreign.
+"""
+
+from __future__ import annotations
+
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+
+from .discovery import discover_skills
+
+KIND_LINK = "link"
+KIND_RELINK = "relink"
+KIND_REMOVE_COPY = "remove-copy"
+KIND_SKIP_FOREIGN = "skip-foreign"
+KIND_OK = "ok"
+
+
+@dataclass(frozen=True)
+class LinkAction:
+    kind: str
+    path: Path
+    target: Path | None
+    reason: str
+
+
+def _points_into(link: Path, root: Path) -> bool:
+    """True when `link` is a symlink resolving inside `root`."""
+    if not link.is_symlink():
+        return False
+    try:
+        resolved = link.resolve()
+    except OSError:
+        return False
+    root_resolved = root.resolve()
+    return resolved == root_resolved or root_resolved in resolved.parents
+
+
+def _plan_one(dest: Path, source: Path, root: Path, clean: bool) -> LinkAction:
+    """Decide what to do with a single destination path.
+
+    Never widens beyond an exact name match — the caller has already established
+    that `dest.name` is one of our skills.
+    """
+    if dest.is_symlink():
+        if _points_into(dest, root):
+            if dest.resolve() == source.resolve():
+                return LinkAction(KIND_OK, dest, source, "already linked")
+            return LinkAction(KIND_RELINK, dest, source, "symlink points at a different repo skill")
+        return LinkAction(KIND_SKIP_FOREIGN, dest, None, "symlink points outside the repo — left untouched")
+
+    if dest.exists():
+        if clean:
+            return LinkAction(KIND_REMOVE_COPY, dest, source, "stale copied directory replaced by a symlink")
+        return LinkAction(KIND_SKIP_FOREIGN, dest, None, "real directory present — rerun with --clean to replace")
+
+    return LinkAction(KIND_LINK, dest, source, "new link")
+
+
+def plan_links(root: Path, home: Path, clean: bool) -> list[LinkAction]:
+    """Compute every filesystem action needed to link this repo's skills into `home`."""
+    agents_dir = home / ".agents" / "skills"
+    claude_dir = home / ".claude" / "skills"
+    actions: list[LinkAction] = []
+    for ctx in discover_skills(root):
+        source = ctx.path
+        actions.append(_plan_one(agents_dir / ctx.name, source, root, clean))
+        actions.append(_plan_one(claude_dir / ctx.name, source, root, clean))
+    return actions
+
+
+def apply_links(actions: list[LinkAction]) -> int:
+    """Execute a plan. Returns the number of filesystem changes made."""
+    changed = 0
+    for action in actions:
+        if action.kind in (KIND_OK, KIND_SKIP_FOREIGN) or action.target is None:
+            continue
+        action.path.parent.mkdir(parents=True, exist_ok=True)
+        if action.kind == KIND_REMOVE_COPY:
+            shutil.rmtree(action.path)
+        elif action.kind == KIND_RELINK:
+            action.path.unlink()
+        action.path.symlink_to(action.target, target_is_directory=True)
+        changed += 1
+    return changed

kctl_skill/lint.py

@@ -0,0 +1,33 @@
+"""Run the SKILL-* rule family over one skill or the whole tree."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from . import rules as _rules  # noqa: F401  (importing registers every rule)
+from .discovery import discover_skills
+from .model import SEVERITY_ERROR, Finding, SkillCtx
+from .parser import parse_skill_md
+from .registry import RULES
+
+
+def lint_skill(ctx: SkillCtx) -> list[Finding]:
+    parsed = parse_skill_md(ctx.skill_md())
+    out: list[Finding] = []
+    for _rule, check in RULES:
+        out.extend(check(ctx, parsed))
+    return out
+
+
+def lint_all(root: Path, names: list[str] | None = None) -> list[Finding]:
+    wanted = set(names) if names else None
+    findings: list[Finding] = []
+    for ctx in discover_skills(root):
+        if wanted is not None and ctx.name not in wanted:
+            continue
+        findings.extend(lint_skill(ctx))
+    return sorted(findings, key=lambda f: (f.location, f.rule_id))
+
+
+def has_errors(findings: list[Finding]) -> bool:
+    return any(f.severity == SEVERITY_ERROR for f in findings)

kctl_skill/model.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+TIER_TOOL = "tool"
+TIER_DOMAIN = "domain"
+VALID_TIERS = (TIER_TOOL, TIER_DOMAIN)
+
+SEVERITY_ERROR = "error"
+SEVERITY_WARN = "warn"
+
+
+@dataclass(frozen=True)
+class SkillConfig:
+    """Parsed skill.toml. The toolchain's only control surface for a skill."""
+
+    tier: str = TIER_DOMAIN
+    cli: str | None = None
+    references: dict[str, list[str]] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class SkillCtx:
+    name: str
+    path: Path
+    config: SkillConfig
+
+    def skill_md(self) -> Path:
+        return self.path / "SKILL.md"
+
+    def skill_toml(self) -> Path:
+        return self.path / "skill.toml"
+
+    def references_dir(self) -> Path:
+        return self.path / "references"
+
+    def evals_dir(self) -> Path:
+        return self.path / "evals"
+
+    def rel(self, root: Path) -> str:
+        return self.path.relative_to(root).as_posix()
+
+
+@dataclass(frozen=True)
+class Frontmatter:
+    name: str
+    description: str
+    extra: dict[str, object] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class ParsedSkill:
+    frontmatter: Frontmatter | None
+    body: str
+    body_lines: int
+    error: str | None = None
+
+
+@dataclass(frozen=True)
+class Finding:
+    rule_id: str
+    location: str
+    detail: str
+    severity: str
+
+    def key(self) -> str:
+        return f"{self.rule_id}::{self.location}"
+
+
+@dataclass(frozen=True)
+class SkillRule:
+    id: str
+    severity: str
+    title: str
+    rationale: str