codepp 0.0.437__py3-none-any.whl

code_puppy/plugins/agent_skills/downloader.py

@@ -0,0 +1,392 @@
+"""Remote skill downloader/installer.
+
+Downloads a remote skill ZIP and installs it into the local skills directory.
+
+Security notes:
+- Defends against zip-slip path traversal.
+- Defends (somewhat) against zip bombs by capping total uncompressed size.
+
+This module never raises to callers; failures are returned as InstallResult.
+"""
+
+from __future__ import annotations
+
+import logging
+import shutil
+import tempfile
+import zipfile
+from pathlib import Path
+from typing import Optional
+
+import httpx
+
+from code_puppy.plugins.agent_skills.discovery import refresh_skill_cache
+from code_puppy.plugins.agent_skills.installer import InstallResult
+
+logger = logging.getLogger(__name__)
+
+_DEFAULT_SKILLS_DIR = Path.home() / ".code_puppy" / "skills"
+_MAX_UNCOMPRESSED_BYTES = 50 * 1024 * 1024  # 50MB
+
+
+def _zip_entry_parts(name: str) -> list[str]:
+    """Return safe-ish path parts for a zip entry.
+
+    Zip files use POSIX-style separators, but malicious zips sometimes include
+    backslashes. We normalize to '/' then split.
+    """
+
+    normalized = name.replace("\\", "/")
+    return [part for part in normalized.split("/") if part not in {"", "."}]
+
+
+def _safe_rmtree(path: Path) -> bool:
+    """Remove a directory tree, logging errors instead of raising."""
+
+    try:
+        if not path.exists():
+            return True
+        shutil.rmtree(path)
+        return True
+    except Exception as e:
+        logger.warning(f"Failed to remove directory {path}: {e}")
+        return False
+
+
+def _download_to_file(url: str, dest: Path) -> bool:
+    """Download a URL to a local file path with streaming."""
+
+    headers = {
+        "Accept": "application/zip, application/octet-stream, */*",
+        "User-Agent": "code-puppy/skill-downloader",
+    }
+
+    try:
+        dest.parent.mkdir(parents=True, exist_ok=True)
+
+        with httpx.Client(timeout=30, headers=headers, follow_redirects=True) as client:
+            with client.stream("GET", url) as response:
+                response.raise_for_status()
+
+                with dest.open("wb") as f:
+                    for chunk in response.iter_bytes():
+                        if chunk:
+                            f.write(chunk)
+
+        logger.info(f"Downloaded skill zip to {dest}")
+        return True
+
+    except httpx.HTTPStatusError as e:
+        logger.warning(
+            "Skill download failed with HTTP status: "
+            f"{e.response.status_code} {e.response.reason_phrase}"
+        )
+        return False
+    except (httpx.ConnectError, httpx.TimeoutException, httpx.NetworkError) as e:
+        logger.warning(f"Skill download network failure: {e}")
+        return False
+    except Exception as e:
+        logger.exception(f"Unexpected error downloading {url}: {e}")
+        return False
+
+
+def _is_within_directory(base_dir: Path, candidate: Path) -> bool:
+    """Check that a path is safely contained within a directory."""
+
+    try:
+        base_resolved = base_dir.resolve()
+        candidate_resolved = candidate.resolve()
+        candidate_resolved.relative_to(base_resolved)
+        return True
+    except Exception:
+        return False
+
+
+def _validate_zip_safety(zf: zipfile.ZipFile) -> Optional[str]:
+    """Return an error message if unsafe, otherwise None."""
+
+    total_uncompressed = 0
+
+    for info in zf.infolist():
+        # Directory entries are fine.
+        if info.is_dir():
+            continue
+
+        total_uncompressed += int(info.file_size or 0)
+        if total_uncompressed > _MAX_UNCOMPRESSED_BYTES:
+            return (
+                "ZIP appears too large when uncompressed "
+                f"(>{_MAX_UNCOMPRESSED_BYTES} bytes)"
+            )
+
+        # Basic zip-slip protection: reject absolute paths and parent traversals.
+        name = info.filename
+        normalized = name.replace("\\", "/")
+        if normalized.startswith("/"):
+            return f"Unsafe zip entry path (absolute): {name}"
+
+        parts = _zip_entry_parts(name)
+        if ".." in parts:
+            return f"Unsafe zip entry path (traversal): {name}"
+
+    return None
+
+
+def _safe_extract_zip(zf: zipfile.ZipFile, extract_dir: Path) -> bool:
+    """Safely extract zip contents into extract_dir."""
+
+    try:
+        extract_dir.mkdir(parents=True, exist_ok=True)
+
+        for info in zf.infolist():
+            parts = _zip_entry_parts(info.filename)
+
+            # Skip weird metadata folders.
+            if parts and parts[0] == "__MACOSX":
+                continue
+
+            dest_path = extract_dir.joinpath(*parts)
+
+            if not _is_within_directory(extract_dir, dest_path):
+                logger.warning(
+                    f"Blocked zip entry outside extraction dir: {info.filename}"
+                )
+                return False
+
+            if info.is_dir():
+                dest_path.mkdir(parents=True, exist_ok=True)
+                continue
+
+            dest_path.parent.mkdir(parents=True, exist_ok=True)
+
+            with zf.open(info, "r") as src, dest_path.open("wb") as dst:
+                shutil.copyfileobj(src, dst)
+
+        return True
+
+    except Exception as e:
+        logger.exception(f"Failed to extract zip safely: {e}")
+        return False
+
+
+def _determine_extracted_root(extract_dir: Path) -> Optional[Path]:
+    """Determine where the skill files live inside an extracted zip.
+
+    Supports:
+    - Files at the zip root
+    - Files inside a single top-level folder
+
+    Returns:
+        Path to the directory containing SKILL.md, or None.
+    """
+
+    try:
+        if (extract_dir / "SKILL.md").is_file():
+            return extract_dir
+
+        children = [p for p in extract_dir.iterdir() if p.name != "__MACOSX"]
+        dirs = [p for p in children if p.is_dir()]
+        files = [p for p in children if p.is_file()]
+
+        # If it's root-level but SKILL.md missing, no good.
+        if files:
+            return None
+
+        if len(dirs) == 1:
+            candidate = dirs[0]
+            if (candidate / "SKILL.md").is_file():
+                return candidate
+
+        return None
+
+    except Exception as e:
+        logger.warning(f"Failed to inspect extracted zip directory {extract_dir}: {e}")
+        return None
+
+
+def _stage_normalized_install(
+    extracted_root: Path, skill_name: str, staging_base: Path
+) -> Optional[Path]:
+    """Copy extracted content into staging_base/<skill_name>."""
+
+    try:
+        staged_skill_dir = staging_base / skill_name
+        if staged_skill_dir.exists():
+            _safe_rmtree(staged_skill_dir)
+
+        shutil.copytree(extracted_root, staged_skill_dir)
+
+        if not (staged_skill_dir / "SKILL.md").is_file():
+            logger.warning(
+                f"Staged skill is missing SKILL.md: {(staged_skill_dir / 'SKILL.md')}"
+            )
+            return None
+
+        return staged_skill_dir
+
+    except Exception as e:
+        logger.exception(f"Failed to stage normalized install for {skill_name}: {e}")
+        return None
+
+
+def download_and_install_skill(
+    skill_name: str,
+    download_url: str,
+    target_dir: Optional[Path] = None,
+    force: bool = False,
+) -> InstallResult:
+    """Download and install a remote skill zip.
+
+    Args:
+        skill_name: Skill name (directory name under target_dir).
+        download_url: Absolute URL to the skill .zip.
+        target_dir: Base skills directory. Defaults to ~/.code_puppy/skills.
+        force: If True, delete any existing install first.
+
+    Returns:
+        InstallResult indicating success/failure.
+    """
+
+    skill_name = skill_name.strip()
+    if not skill_name:
+        return InstallResult(success=False, message="skill_name is required")
+
+    # Prevent path traversal via skill_name.
+    if Path(skill_name).name != skill_name or skill_name in {".", ".."}:
+        return InstallResult(
+            success=False, message="skill_name must be a simple directory name"
+        )
+
+    base_dir = target_dir or _DEFAULT_SKILLS_DIR
+    skill_dir = base_dir / skill_name
+
+    try:
+        if skill_dir.exists():
+            if not force:
+                return InstallResult(
+                    success=False,
+                    message=f"Skill already installed at {skill_dir} (use force=True to reinstall)",
+                    installed_path=skill_dir,
+                )
+
+            logger.info(
+                f"Force reinstall enabled; removing existing skill at {skill_dir}"
+            )
+            if not _safe_rmtree(skill_dir):
+                return InstallResult(
+                    success=False,
+                    message=f"Failed to remove existing skill directory: {skill_dir}",
+                    installed_path=skill_dir,
+                )
+
+        base_dir.mkdir(parents=True, exist_ok=True)
+
+        with tempfile.TemporaryDirectory(prefix="code_puppy_skill_") as tmp:
+            tmp_dir = Path(tmp)
+            tmp_zip = tmp_dir / f"{skill_name}.zip"
+            extract_dir = tmp_dir / "extracted"
+            staging_dir = tmp_dir / "staging"
+            staging_dir.mkdir(parents=True, exist_ok=True)
+
+            if not _download_to_file(download_url, tmp_zip):
+                return InstallResult(
+                    success=False,
+                    message=f"Failed to download skill zip from {download_url}",
+                )
+
+            try:
+                with zipfile.ZipFile(tmp_zip, "r") as zf:
+                    unsafe_reason = _validate_zip_safety(zf)
+                    if unsafe_reason:
+                        logger.warning(
+                            f"Rejected unsafe zip for {skill_name}: {unsafe_reason}"
+                        )
+                        return InstallResult(
+                            success=False,
+                            message=f"Rejected unsafe zip: {unsafe_reason}",
+                        )
+
+                    if not _safe_extract_zip(zf, extract_dir):
+                        return InstallResult(
+                            success=False,
+                            message="Failed to extract skill zip safely",
+                        )
+            except zipfile.BadZipFile:
+                logger.warning(f"Downloaded file is not a valid zip: {tmp_zip}")
+                return InstallResult(
+                    success=False, message="Downloaded file is not a valid zip"
+                )
+            except Exception as e:
+                logger.exception(f"Failed to open/extract zip for {skill_name}: {e}")
+                return InstallResult(success=False, message="Failed to extract zip")
+
+            extracted_root = _determine_extracted_root(extract_dir)
+            if extracted_root is None:
+                logger.warning(
+                    "Extracted zip layout not recognized or missing SKILL.md. "
+                    f"extract_dir={extract_dir}"
+                )
+                return InstallResult(
+                    success=False,
+                    message="Extracted zip missing SKILL.md or has unexpected layout",
+                )
+
+            staged_skill_dir = _stage_normalized_install(
+                extracted_root=extracted_root,
+                skill_name=skill_name,
+                staging_base=staging_dir,
+            )
+            if staged_skill_dir is None:
+                return InstallResult(
+                    success=False,
+                    message="Failed to stage extracted skill (missing SKILL.md)",
+                )
+
+            # Move staged install into final destination.
+            try:
+                if skill_dir.exists():
+                    # Shouldn't happen (handled earlier), but be safe.
+                    if force:
+                        _safe_rmtree(skill_dir)
+                    else:
+                        return InstallResult(
+                            success=False,
+                            message=f"Skill directory already exists: {skill_dir}",
+                            installed_path=skill_dir,
+                        )
+
+                shutil.move(str(staged_skill_dir), str(skill_dir))
+            except Exception as e:
+                logger.exception(f"Failed to install skill into {skill_dir}: {e}")
+                # Cleanup partial install.
+                _safe_rmtree(skill_dir)
+                return InstallResult(
+                    success=False, message="Failed to move skill into place"
+                )
+
+        # Post-install verification.
+        if not (skill_dir / "SKILL.md").is_file():
+            logger.warning(f"Installed skill missing SKILL.md: {skill_dir}")
+            _safe_rmtree(skill_dir)
+            return InstallResult(
+                success=False,
+                message="Installed skill is missing SKILL.md",
+                installed_path=skill_dir,
+            )
+
+        try:
+            refresh_skill_cache()
+        except Exception as e:
+            # Cache refresh failure should not poison a successful install.
+            logger.warning(f"Skill installed but failed to refresh skill cache: {e}")
+
+        logger.info(f"Installed skill '{skill_name}' into {skill_dir}")
+        return InstallResult(
+            success=True,
+            message=f"Installed skill '{skill_name}'",
+            installed_path=skill_dir,
+        )
+
+    except Exception as e:
+        logger.exception(f"Unexpected error installing skill {skill_name}: {e}")
+        return InstallResult(success=False, message="Unexpected error installing skill")

code_puppy/plugins/agent_skills/installer.py

@@ -0,0 +1,22 @@
+"""Agent skills installation helpers.
+
+This module currently provides the shared InstallResult type used by skill
+installers (e.g. local installers, remote zip downloaders).
+
+It is intentionally small so other modules can depend on a stable result shape.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+
+@dataclass(frozen=True, slots=True)
+class InstallResult:
+    """Result of a skill install attempt."""
+
+    success: bool
+    message: str
+    installed_path: Optional[Path] = None

code_puppy/plugins/agent_skills/metadata.py

@@ -0,0 +1,219 @@
+"""Skill metadata parsing - extracts info from SKILL.md frontmatter."""
+
+import logging
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import List, Optional
+
+logger = logging.getLogger(__name__)
+
+# Regex pattern to match YAML frontmatter between --- delimiters
+FRONTMATTER_PATTERN = re.compile(r"^---\s*\n(.*?)\n---\s*\n", re.DOTALL)
+
+# Regex patterns for parsing simple key-value pairs from YAML-like frontmatter
+KEY_VALUE_PATTERN = re.compile(r"^([a-zA-Z_][a-zA-Z0-9_]*):\s*(.*)$", re.MULTILINE)
+LIST_PATTERN = re.compile(r"^\s+-\s+(.+)$", re.MULTILINE)
+
+
+@dataclass
+class SkillMetadata:
+    """Parsed skill metadata from SKILL.md frontmatter."""
+
+    name: str
+    description: str
+    path: Path
+    version: Optional[str] = None
+    author: Optional[str] = None
+    tags: List[str] = field(default_factory=list)
+
+
+def _unquote(value: str) -> str:
+    """Remove quotes from a YAML string value if present."""
+    value = value.strip()
+    if (value.startswith('"') and value.endswith('"')) or (
+        value.startswith("'") and value.endswith("'")
+    ):
+        return value[1:-1]
+    return value
+
+
+def parse_yaml_frontmatter(content: str) -> dict:
+    """Extract YAML frontmatter from SKILL.md content.
+
+    Frontmatter is between --- delimiters at the start of file.
+    Uses simple regex parsing to avoid heavy yaml dependency.
+
+    Args:
+        content: The full content of the SKILL.md file.
+
+    Returns:
+        Dictionary containing parsed frontmatter key-value pairs.
+        Returns empty dict if no frontmatter found or parsing fails.
+    """
+    match = FRONTMATTER_PATTERN.match(content)
+    if not match:
+        logger.debug("No frontmatter found in content")
+        return {}
+
+    frontmatter = match.group(1)
+    result: dict = {}
+    current_key: Optional[str] = None
+    current_list: List[str] = []
+
+    for line in frontmatter.split("\n"):
+        stripped = line.strip()
+
+        # Skip empty lines and comments
+        if not stripped or stripped.startswith("#"):
+            continue
+
+        # Check if this is a list item
+        list_match = LIST_PATTERN.match(line)
+        if list_match and current_key:
+            current_list.append(_unquote(list_match.group(1)))
+            continue
+
+        # Check if this is a key-value pair
+        kv_match = KEY_VALUE_PATTERN.match(line)
+        if kv_match:
+            # Save any accumulated list items from previous key
+            if current_key and current_list:
+                result[current_key] = current_list
+                current_list = []
+
+            key, value = kv_match.groups()
+            key = key.strip()
+            value = value.strip()
+
+            # If value is empty, this might be a list start
+            if not value:
+                current_key = key
+                result[key] = []  # Initialize as empty list
+            else:
+                result[key] = _unquote(value)
+                current_key = None
+
+    # Handle case where list items were at the end
+    if current_key and current_list:
+        result[current_key] = current_list
+
+    return result
+
+
+def parse_skill_metadata(skill_path: Path) -> Optional[SkillMetadata]:
+    """Parse metadata from a skill's SKILL.md file.
+
+    Args:
+        skill_path: Path to the skill directory (not the SKILL.md file)
+
+    Returns:
+        SkillMetadata if successful, None if parsing fails.
+    """
+    if not skill_path.exists():
+        logger.warning(f"Skill path does not exist: {skill_path}")
+        return None
+
+    skill_md_path = skill_path / "SKILL.md"
+    if not skill_md_path.exists():
+        logger.warning(f"SKILL.md not found in skill directory: {skill_path}")
+        return None
+
+    try:
+        content = skill_md_path.read_text(encoding="utf-8")
+    except Exception as e:
+        logger.error(f"Failed to read SKILL.md at {skill_md_path}: {e}")
+        return None
+
+    frontmatter = parse_yaml_frontmatter(content)
+    if not frontmatter:
+        logger.warning(f"No valid frontmatter found in {skill_md_path}")
+        return None
+
+    # Required fields
+    name = frontmatter.get("name")
+    if not name:
+        logger.error(
+            f"'name' is required in frontmatter but not found in {skill_md_path}"
+        )
+        return None
+
+    description = frontmatter.get("description")
+    if not description:
+        logger.error(
+            f"'description' is required in frontmatter but not found in {skill_md_path}"
+        )
+        return None
+
+    # Handle tags - could be a list or a comma-separated string
+    tags: List[str] = []
+    raw_tags = frontmatter.get("tags", [])
+    if isinstance(raw_tags, list):
+        tags = raw_tags
+    elif isinstance(raw_tags, str):
+        tags = [tag.strip() for tag in raw_tags.split(",") if tag.strip()]
+
+    return SkillMetadata(
+        name=name,
+        description=description,
+        path=skill_path,
+        version=frontmatter.get("version"),
+        author=frontmatter.get("author"),
+        tags=tags,
+    )
+
+
+def load_full_skill_content(skill_path: Path) -> Optional[str]:
+    """Load the complete SKILL.md content for activation.
+
+    Args:
+        skill_path: Path to the skill directory
+
+    Returns:
+        Full file content as string, or None if not found.
+    """
+    if not skill_path.exists():
+        logger.warning(f"Skill path does not exist: {skill_path}")
+        return None
+
+    skill_md_path = skill_path / "SKILL.md"
+    if not skill_md_path.exists():
+        logger.warning(f"SKILL.md not found in skill directory: {skill_path}")
+        return None
+
+    try:
+        return skill_md_path.read_text(encoding="utf-8")
+    except Exception as e:
+        logger.error(f"Failed to read SKILL.md at {skill_md_path}: {e}")
+        return None
+
+
+def get_skill_resources(skill_path: Path) -> List[Path]:
+    """List all resource files bundled with a skill.
+
+    Returns paths to all non-SKILL.md files in the skill directory.
+
+    Args:
+        skill_path: Path to the skill directory
+
+    Returns:
+        List of paths to resource files (excluding SKILL.md).
+    """
+    if not skill_path.exists():
+        logger.warning(f"Skill path does not exist: {skill_path}")
+        return []
+
+    if not skill_path.is_dir():
+        logger.warning(f"Skill path is not a directory: {skill_path}")
+        return []
+
+    resources: List[Path] = []
+    try:
+        for item in skill_path.iterdir():
+            if item.is_file() and item.name != "SKILL.md":
+                resources.append(item)
+    except Exception as e:
+        logger.error(f"Failed to list resources in {skill_path}: {e}")
+        return []
+
+    return sorted(resources)  # Sort for consistent ordering

code_puppy/plugins/agent_skills/prompt_builder.py

@@ -0,0 +1,60 @@
+"""Build available_skills XML for system prompt injection."""
+
+from typing import TYPE_CHECKING, List
+
+if TYPE_CHECKING:
+    from .metadata import SkillMetadata
+
+
+def build_available_skills_xml(skills: List["SkillMetadata"]) -> str:
+    """Build Claude-optimized XML listing available skills.
+
+    Args:
+        skills: List of SkillMetadata objects to include in the XML.
+
+    Returns:
+        XML string listing available skills in the format:
+        <available_skills>
+          <skill>
+            <name>skill-name</name>
+            <description>What the skill does...</description>
+          </skill>
+          ...
+        </available_skills>
+
+    To use a skill, call activate_skill(skill_name) to load full instructions.
+    """
+    if not skills:
+        return "<available_skills></available_skills>"
+
+    xml_parts = ["<available_skills>"]
+
+    for skill in skills:
+        xml_parts.append("  <skill>")
+        xml_parts.append(f"    <name>{skill.name}</name>")
+        if skill.description:
+            # Escape any XML special characters in the description
+            escaped_desc = (
+                skill.description.replace("&", "&amp;")
+                .replace("<", "&lt;")
+                .replace(">", "&gt;")
+                .replace('"', "&quot;")
+                .replace("'", "&#39;")
+            )
+            xml_parts.append(f"    <description>{escaped_desc}</description>")
+        xml_parts.append("  </skill>")
+
+    xml_parts.append("</available_skills>")
+
+    return "\n".join(xml_parts)
+
+
+def build_skills_guidance() -> str:
+    """Return guidance text for how to use skills."""
+    return """
+# Agent Skills
+
+When `<available_skills>` appears in context, match user tasks to skill descriptions.
+Call `activate_skill(skill_name)` to load full instructions before starting the task.
+Use `list_or_search_skills(query)` to search for relevant skills.
+"""