code-puppy-core-plugins 0.0.2__py3-none-any.whl

code_puppy_core_plugins/agent_skills/discovery.py

@@ -0,0 +1,337 @@
+"""Skill discovery - scans directories for valid skills."""
+
+import logging
+import shutil
+import threading
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Iterable, List, Optional
+
+from code_puppy.callbacks import get_callbacks, on_register_skills
+from code_puppy.config import CACHE_DIR
+from code_puppy_core_plugins.agent_skills.config import get_skill_directories
+
+logger = logging.getLogger(__name__)
+
+_PLUGIN_SKILLS_CACHE_DIR = Path(CACHE_DIR) / "plugin-skills"
+
+# Serialises the wipe-and-rebuild of the shared plugin-skills cache dir: called from
+# both the main loop and worker threads (anyio to_thread), so without the lock two
+# threads race -- one rmtree's it while the other mkdir's/writes (macOS: OSError 22).
+_PLUGIN_SKILLS_LOCK = threading.Lock()
+
+# Memoised last successful build, keyed by a signature of the (process-deterministic)
+# registrations, so the cache dir is rebuilt only when they change. Also stops a rebuild
+# from tearing the dir out from under lock-free readers of returned SkillInfo.path.
+_plugin_skills_cache: Optional[List["SkillInfo"]] = None
+_plugin_skills_signature: Optional[tuple] = None
+
+
+@dataclass
+class SkillInfo:
+    """Basic skill information from discovery."""
+
+    name: str
+    path: Path
+    has_skill_md: bool
+
+
+# Global cache for discovered skills
+_skill_cache: Optional[List[SkillInfo]] = None
+
+
+def get_default_skill_directories() -> List[Path]:
+    """Return default directories to scan for skills.
+
+    Returns:
+        - ~/.code_puppy/skills (user skills)
+        - ./.code_puppy/skills (project config skills)
+        - ./skills (project skills)
+    """
+    return [
+        Path.home() / ".code_puppy" / "skills",
+        Path.cwd() / ".code_puppy" / "skills",
+        Path.cwd() / "skills",
+    ]
+
+
+def is_valid_skill_directory(path: Path) -> bool:
+    """Check if a directory contains a valid SKILL.md file."""
+    if not path.is_dir():
+        return False
+
+    skill_md_path = path / "SKILL.md"
+    return skill_md_path.is_file()
+
+
+def _sanitize_path_part(value: str) -> str:
+    cleaned = (value or "").strip().replace("/", "-").replace("\\", "-")
+    return cleaned or "unnamed"
+
+
+def _render_skill_markdown(entry: dict[str, Any]) -> str:
+    if "skill_md" in entry:
+        return str(entry["skill_md"])
+
+    if "skill_md_path" in entry:
+        return Path(entry["skill_md_path"]).read_text(encoding="utf-8")
+
+    if "frontmatter" in entry and "body" in entry:
+        frontmatter = dict(entry["frontmatter"] or {})
+        frontmatter.setdefault("name", entry["name"])
+        if entry.get("description") and "description" not in frontmatter:
+            frontmatter["description"] = entry["description"]
+        if entry.get("version") and "version" not in frontmatter:
+            frontmatter["version"] = entry["version"]
+        if entry.get("author") and "author" not in frontmatter:
+            frontmatter["author"] = entry["author"]
+        if entry.get("tags") and "tags" not in frontmatter:
+            frontmatter["tags"] = entry["tags"]
+
+        lines = ["---"]
+        for key, value in frontmatter.items():
+            if isinstance(value, list):
+                lines.append(f"{key}:")
+                for item in value:
+                    lines.append(f"  - {item}")
+            else:
+                lines.append(f"{key}: {value}")
+        lines.extend(["---", str(entry["body"])])
+        return "\n".join(lines).rstrip() + "\n"
+
+    raise ValueError(
+        "Skill entry must define either skill_md_path, skill_md, or frontmatter+body"
+    )
+
+
+def _copy_scripts_dir(source_dir: Path, target_dir: Path) -> None:
+    scripts_target = target_dir / "scripts"
+    if scripts_target.exists() or scripts_target.is_symlink():
+        if scripts_target.is_dir() and not scripts_target.is_symlink():
+            shutil.rmtree(scripts_target)
+        else:
+            scripts_target.unlink()
+
+    try:
+        scripts_target.symlink_to(source_dir, target_is_directory=True)
+    except OSError:
+        shutil.copytree(source_dir, scripts_target)
+
+
+def _materialize_plugin_skill(
+    callback_module: str, callback_name: str, entry: dict[str, Any]
+) -> SkillInfo | None:
+    skill_name = str(entry.get("name") or "").strip()
+    if not skill_name:
+        logger.warning(
+            "Plugin skill registration from %s.%s missing required 'name'",
+            callback_module,
+            callback_name,
+        )
+        return None
+
+    try:
+        skill_md = _render_skill_markdown(entry)
+    except Exception as exc:
+        logger.warning(
+            "Failed to render plugin skill %s from %s.%s: %s",
+            skill_name,
+            callback_module,
+            callback_name,
+            exc,
+        )
+        return None
+
+    owner_dir = _PLUGIN_SKILLS_CACHE_DIR / _sanitize_path_part(callback_module)
+    skill_dir = owner_dir / _sanitize_path_part(skill_name)
+    skill_dir.mkdir(parents=True, exist_ok=True)
+    (skill_dir / "SKILL.md").write_text(skill_md, encoding="utf-8")
+
+    scripts_dir = entry.get("scripts_dir")
+    if scripts_dir:
+        source_dir = Path(scripts_dir).expanduser().resolve()
+        if source_dir.is_dir():
+            _copy_scripts_dir(source_dir, skill_dir)
+        else:
+            logger.warning(
+                "Plugin skill %s from %s.%s provided invalid scripts_dir: %s",
+                skill_name,
+                callback_module,
+                callback_name,
+                source_dir,
+            )
+
+    return SkillInfo(name=skill_name, path=skill_dir, has_skill_md=True)
+
+
+def _iter_plugin_skill_registrations() -> Iterable[tuple[str, str, dict[str, Any]]]:
+    callbacks = get_callbacks("register_skills")
+    results = on_register_skills()
+
+    for callback, result in zip(callbacks, results):
+        if not result:
+            continue
+        if not isinstance(result, list):
+            logger.warning(
+                "register_skills callback %s.%s must return a list, got %s",
+                callback.__module__,
+                callback.__name__,
+                type(result).__name__,
+            )
+            continue
+
+        for entry in result:
+            if not isinstance(entry, dict):
+                logger.warning(
+                    "register_skills callback %s.%s returned non-dict entry: %r",
+                    callback.__module__,
+                    callback.__name__,
+                    entry,
+                )
+                continue
+            # Provider registrations are consumed by core through the same
+            # hook; they are capabilities, not skills to materialize.
+            if "provider" in entry:
+                continue
+            yield callback.__module__, callback.__name__, entry
+
+
+def _plugin_registration_signature(
+    registrations: List[tuple[str, str, dict[str, Any]]],
+) -> tuple:
+    """Deterministic signature of the plugin skill registrations.
+
+    Used to decide whether the on-disk cache still reflects the registered
+    skills. Sorting each entry's items by key keeps the signature stable
+    regardless of dict ordering.
+    """
+    return tuple(
+        (module, name, repr(sorted(entry.items(), key=lambda kv: kv[0])))
+        for module, name, entry in registrations
+    )
+
+
+def _collect_plugin_skills() -> List[SkillInfo]:
+    global _plugin_skills_cache, _plugin_skills_signature
+
+    with _PLUGIN_SKILLS_LOCK:
+        registrations = list(_iter_plugin_skill_registrations())
+        signature = _plugin_registration_signature(registrations)
+
+        # Reuse the materialised cache when registrations are unchanged and files are
+        # still on disk. Skipping the wipe prevents a concurrent rebuild from deleting
+        # a SKILL.md while a lock-free reader is consuming an earlier returned path.
+        if (
+            _plugin_skills_cache is not None
+            and signature == _plugin_skills_signature
+            and _PLUGIN_SKILLS_CACHE_DIR.exists()
+        ):
+            return list(_plugin_skills_cache)
+
+        if _PLUGIN_SKILLS_CACHE_DIR.exists():
+            shutil.rmtree(_PLUGIN_SKILLS_CACHE_DIR, ignore_errors=True)
+        _PLUGIN_SKILLS_CACHE_DIR.mkdir(parents=True, exist_ok=True)
+
+        plugin_skills: List[SkillInfo] = []
+        seen_names: set[str] = set()
+
+        for callback_module, callback_name, entry in registrations:
+            skill = _materialize_plugin_skill(callback_module, callback_name, entry)
+            if skill is None:
+                continue
+            if skill.name in seen_names:
+                logger.warning(
+                    "Skipping duplicate plugin skill registration for '%s' from %s.%s",
+                    skill.name,
+                    callback_module,
+                    callback_name,
+                )
+                continue
+            seen_names.add(skill.name)
+            plugin_skills.append(skill)
+
+        _plugin_skills_cache = plugin_skills
+        _plugin_skills_signature = signature
+        return list(plugin_skills)
+
+
+def discover_skills(directories: Optional[List[Path]] = None) -> List[SkillInfo]:
+    """Scan directories for valid skills."""
+    global _skill_cache
+
+    if directories is None:
+        configured = [Path(d) for d in get_skill_directories()]
+        defaults = get_default_skill_directories()
+        seen = {p.resolve() for p in configured}
+        directories = list(configured)
+        for d in defaults:
+            if d.resolve() not in seen:
+                directories.append(d)
+
+    discovered_skills: List[SkillInfo] = []
+    seen_skill_names: set[str] = set()
+
+    for directory in directories:
+        if not directory.exists():
+            logger.debug(f"Skill directory does not exist: {directory}")
+            continue
+
+        if not directory.is_dir():
+            logger.warning(f"Skill path is not a directory: {directory}")
+            continue
+
+        for skill_dir in directory.iterdir():
+            if not skill_dir.is_dir() or skill_dir.name.startswith("."):
+                continue
+
+            # First-discovered skill wins - skip duplicates from later directories
+            if skill_dir.name in seen_skill_names:
+                logger.debug(
+                    "Skipping duplicate skill '%s' at %s (already discovered)",
+                    skill_dir.name,
+                    skill_dir,
+                )
+                continue
+
+            has_skill_md = is_valid_skill_directory(skill_dir)
+            skill_info = SkillInfo(
+                name=skill_dir.name,
+                path=skill_dir,
+                has_skill_md=has_skill_md,
+            )
+            discovered_skills.append(skill_info)
+            seen_skill_names.add(skill_info.name)
+
+            if has_skill_md:
+                logger.debug(
+                    "Discovered valid skill: %s at %s", skill_dir.name, skill_dir
+                )
+            else:
+                logger.debug(
+                    "Found skill directory without SKILL.md: %s", skill_dir.name
+                )
+
+    for plugin_skill in _collect_plugin_skills():
+        if plugin_skill.name in seen_skill_names:
+            logger.debug(
+                "Skipping plugin skill '%s' because a filesystem skill already exists",
+                plugin_skill.name,
+            )
+            continue
+        discovered_skills.append(plugin_skill)
+        seen_skill_names.add(plugin_skill.name)
+
+    _skill_cache = discovered_skills
+    logger.info(
+        "Discovered %s skills from %s directories",
+        len(discovered_skills),
+        len(directories),
+    )
+    return discovered_skills
+
+
+def refresh_skill_cache() -> List[SkillInfo]:
+    """Force re-discovery of all skills."""
+    global _skill_cache
+    _skill_cache = None
+    return discover_skills()