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

code_puppy_core_plugins/agent_skills/remote_catalog.py

@@ -0,0 +1,322 @@
+"""Remote skills catalog client.
+
+Fetches the remote skills catalog JSON and exposes a cached, parsed view.
+
+Design goals:
+- Never crash the app (defensive parsing + broad error handling).
+- Local caching with TTL for fast startup and offline use.
+- Synchronous networking only (httpx.Client).
+
+Schema source:
+https://www.llmspec.dev/skills/skills.json
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Optional
+from urllib.parse import urljoin
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+SKILLS_JSON_URL = "https://www.llmspec.dev/skills/skills.json"
+
+_CACHE_DIR = Path.home() / ".code_puppy" / "cache"
+_CACHE_PATH = _CACHE_DIR / "skills_catalog.json"
+_CACHE_TTL_SECONDS = 30 * 60
+
+
+@dataclass(frozen=True, slots=True)
+class RemoteSkillEntry:
+    """Flattened remote skill entry."""
+
+    name: str
+    description: str
+    group: str
+    download_url: str
+    zip_size_bytes: int
+    file_count: int
+    has_scripts: bool
+    has_references: bool
+    has_license: bool
+
+
+@dataclass(frozen=True, slots=True)
+class RemoteCatalogData:
+    """Parsed remote catalog.
+
+    Attributes:
+        version: Catalog version string.
+        base_url: Base URL used to build absolute download_url values.
+        total_skills: Total number of skills in the remote catalog.
+        groups: Raw group objects from the JSON (kept as dicts for flexibility).
+        entries: Flattened list of all skills across all groups.
+    """
+
+    version: str
+    base_url: str
+    total_skills: int
+    groups: list[dict[str, Any]]
+    entries: list[RemoteSkillEntry]
+
+
+def _safe_int(value: Any, default: int = 0) -> int:
+    """Convert value to int, returning default on failure."""
+
+    try:
+        if value is None:
+            return default
+        return int(value)
+    except Exception:
+        return default
+
+
+def _safe_bool(value: Any, default: bool = False) -> bool:
+    """Convert value to bool, returning default on failure."""
+
+    if value is None:
+        return default
+    return bool(value)
+
+
+def _cache_is_fresh(cache_path: Path, ttl_seconds: int) -> bool:
+    """Check whether the on-disk catalog cache is within TTL."""
+
+    try:
+        if not cache_path.exists():
+            return False
+        age_seconds = time.time() - cache_path.stat().st_mtime
+        return age_seconds <= ttl_seconds
+    except Exception as e:
+        logger.debug(f"Failed to check cache age for {cache_path}: {e}")
+        return False
+
+
+def _read_cache(cache_path: Path) -> Optional[dict[str, Any]]:
+    """Read and deserialize the cached catalog JSON from disk."""
+
+    try:
+        if not cache_path.exists():
+            return None
+        raw = cache_path.read_text(encoding="utf-8")
+        data = json.loads(raw)
+        if not isinstance(data, dict):
+            logger.warning(f"Cache JSON is not an object: {cache_path}")
+            return None
+        return data
+    except Exception as e:
+        logger.warning(f"Failed to read cache {cache_path}: {e}")
+        return None
+
+
+def _write_cache(cache_path: Path, data: dict[str, Any]) -> bool:
+    """Serialize and write catalog JSON to the disk cache."""
+
+    try:
+        cache_path.parent.mkdir(parents=True, exist_ok=True)
+        # Stable formatting so diffs are readable when debugging.
+        cache_path.write_text(
+            json.dumps(data, indent=2, sort_keys=True) + "\n", encoding="utf-8"
+        )
+        return True
+    except Exception as e:
+        logger.warning(f"Failed to write cache {cache_path}: {e}")
+        return False
+
+
+def _fetch_remote_json(url: str) -> Optional[dict[str, Any]]:
+    """Fetch the skills catalog JSON from the remote URL."""
+
+    headers = {
+        "Accept": "application/json",
+        "User-Agent": "code-puppy/remote-catalog",
+    }
+
+    try:
+        with httpx.Client(timeout=15, headers=headers) as client:
+            response = client.get(url)
+            response.raise_for_status()
+            data = response.json()
+
+        if not isinstance(data, dict):
+            logger.error(f"Remote catalog JSON was not an object. Got: {type(data)}")
+            return None
+
+        return data
+
+    except httpx.HTTPStatusError as e:
+        logger.warning(
+            "Remote catalog request returned bad status: "
+            f"{e.response.status_code} {e.response.reason_phrase}"
+        )
+        return None
+    except (httpx.ConnectError, httpx.TimeoutException, httpx.NetworkError) as e:
+        logger.warning(f"Remote catalog network failure: {e}")
+        return None
+    except json.JSONDecodeError as e:
+        logger.warning(f"Remote catalog returned invalid JSON: {e}")
+        return None
+    except Exception as e:
+        logger.exception(f"Unexpected error fetching remote catalog: {e}")
+        return None
+
+
+def _parse_catalog(raw: dict[str, Any]) -> Optional[RemoteCatalogData]:
+    """Parse raw JSON dicts into a list of RemoteSkillEntry objects."""
+
+    try:
+        version = str(raw.get("version") or "")
+        base_url = str(raw.get("base_url") or "")
+        total_skills = _safe_int(raw.get("total_skills"), default=0)
+
+        raw_groups = raw.get("groups")
+        if not isinstance(raw_groups, list):
+            logger.warning("Remote catalog 'groups' missing or not a list")
+            raw_groups = []
+
+        groups: list[dict[str, Any]] = []
+        entries: list[RemoteSkillEntry] = []
+
+        # Ensure urljoin behaves (needs trailing slash on base).
+        base_for_join = base_url.rstrip("/") + "/" if base_url else ""
+
+        for group_obj in raw_groups:
+            if not isinstance(group_obj, dict):
+                continue
+            groups.append(group_obj)
+
+            group_slug = str(group_obj.get("slug") or group_obj.get("name") or "")
+            skills = group_obj.get("skills")
+            if not isinstance(skills, list):
+                continue
+
+            for skill in skills:
+                if not isinstance(skill, dict):
+                    continue
+
+                name = str(skill.get("name") or "").strip()
+                if not name:
+                    # If name is missing, it can't be indexed/activated anyway.
+                    continue
+
+                description = str(skill.get("description") or "")
+                group = str(skill.get("group") or group_slug or "")
+
+                download_path = str(skill.get("download_url") or "")
+                download_url = (
+                    urljoin(base_for_join, download_path)
+                    if base_for_join
+                    else download_path
+                )
+
+                contents = skill.get("contents")
+                if not isinstance(contents, dict):
+                    contents = {}
+
+                entries.append(
+                    RemoteSkillEntry(
+                        name=name,
+                        description=description,
+                        group=group,
+                        download_url=download_url,
+                        zip_size_bytes=_safe_int(
+                            skill.get("zip_size_bytes"), default=0
+                        ),
+                        file_count=_safe_int(skill.get("file_count"), default=0),
+                        has_scripts=_safe_bool(
+                            contents.get("has_scripts"), default=False
+                        ),
+                        has_references=_safe_bool(
+                            contents.get("has_references"), default=False
+                        ),
+                        has_license=_safe_bool(
+                            contents.get("has_license"), default=False
+                        ),
+                    )
+                )
+
+        if not version:
+            logger.debug("Remote catalog 'version' is missing/empty")
+        if not base_url:
+            logger.debug("Remote catalog 'base_url' is missing/empty")
+
+        return RemoteCatalogData(
+            version=version,
+            base_url=base_url,
+            total_skills=total_skills,
+            groups=groups,
+            entries=entries,
+        )
+
+    except Exception as e:
+        logger.exception(f"Failed to parse remote catalog JSON: {e}")
+        return None
+
+
+def fetch_remote_catalog(force_refresh: bool = False) -> Optional[RemoteCatalogData]:
+    """Fetch the remote skills catalog with caching and offline fallback.
+
+    Cache behavior:
+    - Cache file: ~/.code_puppy/cache/skills_catalog.json
+    - TTL: 30 minutes (based on file mtime)
+    - Offline fallback: if network fetch fails, use cache if present (even if expired)
+
+    Args:
+        force_refresh: If True, always attempt a network fetch.
+
+    Returns:
+        Parsed RemoteCatalogData on success, otherwise None.
+    """
+
+    cache_fresh = _cache_is_fresh(_CACHE_PATH, _CACHE_TTL_SECONDS)
+
+    # Use fresh cache unless forced.
+    if not force_refresh and cache_fresh:
+        logger.info(f"Using fresh remote catalog cache: {_CACHE_PATH}")
+        cached = _read_cache(_CACHE_PATH)
+        if cached is None:
+            logger.warning("Fresh cache exists but could not be read; refetching")
+        else:
+            parsed = _parse_catalog(cached)
+            if parsed is not None:
+                return parsed
+            logger.warning("Fresh cache exists but could not be parsed; refetching")
+
+    if force_refresh:
+        logger.info("Force refresh enabled; fetching remote skills catalog")
+    elif _CACHE_PATH.exists():
+        logger.info(
+            "Cache is missing or stale; fetching remote skills catalog "
+            f"(cache_path={_CACHE_PATH}, fresh={cache_fresh})"
+        )
+    else:
+        logger.info("No cache present; fetching remote skills catalog")
+
+    remote_raw = _fetch_remote_json(SKILLS_JSON_URL)
+    if remote_raw is not None:
+        logger.info("Fetched remote skills catalog successfully")
+        _write_cache(_CACHE_PATH, remote_raw)
+        parsed = _parse_catalog(remote_raw)
+        if parsed is not None:
+            return parsed
+        logger.warning("Remote catalog fetched but failed to parse")
+
+    # Offline fallback: use cache even if expired.
+    if _CACHE_PATH.exists():
+        logger.warning(
+            "Remote fetch failed; falling back to cached skills catalog "
+            f"(even if expired): {_CACHE_PATH}"
+        )
+        cached = _read_cache(_CACHE_PATH)
+        if cached is None:
+            return None
+        return _parse_catalog(cached)
+
+    logger.error("Remote fetch failed and no cache is available")
+    return None

code_puppy_core_plugins/agent_skills/skill_catalog.py

@@ -0,0 +1,257 @@
+"""Remote-backed skill catalog adapter.
+
+This module provides a stable public interface for the rest of the codebase.
+Historically, code_puppy used a local static catalog. We now source skills from
+`remote_catalog.fetch_remote_catalog()` while keeping the same access patterns.
+
+Public API:
+    from code_puppy_core_plugins.agent_skills.skill_catalog import (
+        SkillCatalog,
+        SkillCatalogEntry,
+        _format_display_name,
+        catalog,
+    )
+
+If the remote catalog can't be fetched (and there's no cache), the catalog is
+empty by default (and we log a warning).
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import List, Optional
+
+from code_puppy_core_plugins.agent_skills.remote_catalog import fetch_remote_catalog
+
+logger = logging.getLogger(__name__)
+
+
+_ACRONYMS = {
+    "ai",
+    "api",
+    "aws",
+    "cli",
+    "cpu",
+    "csv",
+    "db",
+    "dns",
+    "gpu",
+    "html",
+    "http",
+    "https",
+    "id",
+    "json",
+    "jwt",
+    "k8s",
+    "llm",
+    "ml",
+    "mvp",
+    "oauth",
+    "pdf",
+    "psql",
+    "qa",
+    "rest",
+    "rpc",
+    "sdk",
+    "sql",
+    "ssh",
+    "ssl",
+    "tls",
+    "tsv",
+    "ui",
+    "url",
+    "utc",
+    "uuid",
+    "xml",
+    "yaml",
+    "yml",
+}
+
+
+def _format_display_name(skill_id: str) -> str:
+    """Format a human-readable display name from a skill id.
+
+    Examples:
+        data-exploration -> Data Exploration
+        pdf -> PDF
+
+    This is intentionally simple and predictable.
+    """
+
+    cleaned = (skill_id or "").strip()
+    if not cleaned:
+        return ""
+
+    parts = [p for p in cleaned.replace("_", "-").split("-") if p]
+    formatted: list[str] = []
+
+    for part in parts:
+        lower = part.lower()
+        if lower in _ACRONYMS:
+            formatted.append(lower.upper())
+        else:
+            # Keep existing capitalization for words like "Nextflow" if provided,
+            # otherwise just Title Case.
+            formatted.append(part[:1].upper() + part[1:].lower())
+
+    return " ".join(formatted)
+
+
+@dataclass(frozen=True, slots=True)
+class SkillCatalogEntry:
+    """Catalog entry for a skill.
+
+    Fields are designed to match the historical local catalog interface while
+    including remote-only fields (download_url, zip_size_bytes).
+    """
+
+    id: str
+    name: str
+    display_name: str
+    description: str
+    category: str
+    tags: List[str] = field(default_factory=list)
+    source_path: Optional[Path] = None
+    has_scripts: bool = False
+    has_references: bool = False
+    file_count: int = 0
+    download_url: str = ""
+    zip_size_bytes: int = 0
+
+
+class SkillCatalog:
+    """Remote skill catalog.
+
+    This class is a simple in-memory index over remote catalog entries.
+    """
+
+    def __init__(self) -> None:
+        """Initialize the skill catalog with empty indices."""
+
+        self._entries: list[SkillCatalogEntry] = []
+        self._by_id: dict[str, SkillCatalogEntry] = {}
+        self._by_category: dict[str, list[SkillCatalogEntry]] = {}
+
+        try:
+            remote = fetch_remote_catalog()
+        except Exception as e:
+            # fetch_remote_catalog should already be defensive, but let's be extra safe.
+            logger.warning(f"Failed to fetch remote catalog: {e}")
+            remote = None
+
+        if remote is None:
+            logger.warning(
+                "Remote skill catalog unavailable (no network and no cache). "
+                "Catalog will be empty."
+            )
+            return
+
+        entries: list[SkillCatalogEntry] = []
+
+        for remote_entry in remote.entries:
+            skill_id = remote_entry.name
+            entry = SkillCatalogEntry(
+                id=skill_id,
+                name=remote_entry.name,
+                display_name=_format_display_name(remote_entry.name),
+                description=remote_entry.description,
+                category=remote_entry.group,
+                tags=[],
+                source_path=None,
+                has_scripts=remote_entry.has_scripts,
+                has_references=remote_entry.has_references,
+                file_count=remote_entry.file_count,
+                download_url=remote_entry.download_url,
+                zip_size_bytes=remote_entry.zip_size_bytes,
+            )
+            entries.append(entry)
+
+        self._rebuild_indices(entries)
+
+        logger.info(
+            f"Loaded remote skill catalog: {len(self._entries)} skills in "
+            f"{len(self._by_category)} categories"
+        )
+
+    def _rebuild_indices(self, entries: list[SkillCatalogEntry]) -> None:
+        """Rebuild internal lookup indices from the loaded entries."""
+
+        self._entries = list(entries)
+        self._by_id = {}
+        self._by_category = {}
+
+        for entry in self._entries:
+            # Last one wins if duplicates somehow exist.
+            self._by_id[entry.id] = entry
+
+            cat_key = (entry.category or "").casefold()
+            self._by_category.setdefault(cat_key, []).append(entry)
+
+        # Keep category lists stable and predictable.
+        for cat_entries in self._by_category.values():
+            cat_entries.sort(key=lambda e: e.display_name.casefold())
+
+        self._entries.sort(key=lambda e: e.display_name.casefold())
+
+    def list_categories(self) -> List[str]:
+        """List all categories."""
+
+        categories = {e.category for e in self._entries if e.category}
+        return sorted(categories, key=lambda c: c.casefold())
+
+    def get_by_category(self, category: str) -> List[SkillCatalogEntry]:
+        """Return all entries in a category (case-insensitive)."""
+
+        if not category:
+            return []
+        return list(self._by_category.get(category.casefold(), []))
+
+    def search(self, query: str) -> List[SkillCatalogEntry]:
+        """Search by substring over id/name/display_name/description/tags/category."""
+
+        q = (query or "").strip().casefold()
+        if not q:
+            return self.get_all()
+
+        results: list[SkillCatalogEntry] = []
+        for entry in self._entries:
+            haystacks = [
+                entry.id,
+                entry.name,
+                entry.display_name,
+                entry.description,
+                entry.category,
+                " ".join(entry.tags),
+            ]
+
+            if any(q in (h or "").casefold() for h in haystacks):
+                results.append(entry)
+
+        return results
+
+    def get_by_id(self, skill_id: str) -> Optional[SkillCatalogEntry]:
+        """Get a skill entry by id (case-sensitive exact match)."""
+
+        if not skill_id:
+            return None
+        return self._by_id.get(skill_id)
+
+    def get_all(self) -> List[SkillCatalogEntry]:
+        """Return all entries."""
+
+        return list(self._entries)
+
+
+# Singleton instance used by the rest of the codebase.
+# NOTE: This must never crash import-time.
+catalog = SkillCatalog()
+
+
+__all__ = [
+    "SkillCatalog",
+    "SkillCatalogEntry",
+    "_format_display_name",
+    "catalog",
+]

code_puppy_core_plugins/agent_skills/skill_commands.py

@@ -0,0 +1,102 @@
+"""Per-skill slash commands.
+
+Each discovered (and enabled) skill is exposed as a ``/<skill-name>`` slash
+command.  Invoking it loads the full ``SKILL.md`` content and submits it
+as the prompt — effectively the same thing the ``activate_skill`` tool
+does, only initiated by the user.
+
+This lives in its own module so that ``register_callbacks.py`` stays
+focused on wiring callbacks (SRP, and the file-size cap).
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, List, Optional, Tuple
+
+from code_puppy.messaging import emit_info
+
+logger = logging.getLogger(__name__)
+
+# Slash command names already owned by the skills plugin itself.
+# We must never shadow them with a per-skill command.
+_RESERVED_NAMES = {"skills", "skill"}
+
+
+def _iter_enabled_skills():
+    """Yield ``SkillMetadata`` for every enabled, valid, non-reserved skill.
+
+    Delegates the disabled / has_skill_md filtering to
+    :func:`enabled_skills.iter_enabled_skill_metadata`, so disabled skills
+    never get their frontmatter loaded here either.
+    """
+    from .enabled_skills import iter_enabled_skill_metadata
+
+    for meta in iter_enabled_skill_metadata():
+        if meta.name in _RESERVED_NAMES:
+            logger.debug(
+                "Skipping skill %r: name collides with reserved slash command",
+                meta.name,
+            )
+            continue
+        yield meta
+
+
+def skill_command_help() -> List[Tuple[str, str]]:
+    """Advertise every enabled skill in the ``/help`` menu."""
+    entries: List[Tuple[str, str]] = []
+    for meta in _iter_enabled_skills():
+        desc = meta.description or "(no description)"
+        # Trim ridiculously long descriptions for the help table.
+        if len(desc) > 80:
+            desc = desc[:77] + "..."
+        entries.append((meta.name, f"🛠️  Skill: {desc}"))
+    return entries
+
+
+def handle_skill_command(command: str, name: str) -> Optional[Any]:
+    """Return the SKILL.md content as a MarkdownCommandResult if ``name``
+    matches an enabled skill, otherwise ``None``.
+
+    Extra args after the command are appended as ``Additional context:``,
+    mirroring the customizable_commands plugin's contract.
+    """
+    if not name or name in _RESERVED_NAMES:
+        return None
+
+    # Lazy import to avoid a hard dependency on customizable_commands at
+    # plugin load time (and to keep things tidy if it ever moves).
+    try:
+        from code_puppy_core_plugins.customizable_commands.register_callbacks import (
+            MarkdownCommandResult,
+        )
+    except ImportError:
+        logger.debug("MarkdownCommandResult unavailable; cannot run skill via slash")
+        return None
+
+    # Find a matching enabled skill.
+    match = next((m for m in _iter_enabled_skills() if m.name == name), None)
+    if match is None:
+        return None
+
+    from .metadata import load_full_skill_content
+
+    content = load_full_skill_content(match.path)
+    if not content:
+        logger.warning("Failed to load SKILL.md for %s", match.name)
+        return None
+
+    # Allow user to pass freeform args after the slash command.
+    parts = command.split(maxsplit=1)
+    args = parts[1].strip() if len(parts) > 1 else ""
+
+    header = (
+        f"You are activating the '{match.name}' skill. Follow its "
+        f"SKILL.md instructions below verbatim.\n\n"
+    )
+    prompt = header + content
+    if args:
+        prompt = f"{prompt}\n\nAdditional context: {args}"
+
+    emit_info(f"🛠️  Activating skill via slash command: {match.name}")
+    return MarkdownCommandResult(prompt)