gobby 0.2.5__py3-none-any.whl → 0.2.7__py3-none-any.whl

gobby/skills/manager.py

@@ -0,0 +1,384 @@
+"""SkillManager - Coordinator for skill storage and search.
+
+This module provides the SkillManager class which coordinates:
+- Storage operations (LocalSkillManager)
+- Search functionality (SkillSearch)
+- Change notifications for automatic reindexing
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any
+
+from gobby.skills.search import SearchFilters, SkillSearch, SkillSearchResult
+from gobby.storage.skills import (
+    ChangeEvent,
+    LocalSkillManager,
+    Skill,
+    SkillChangeNotifier,
+    SkillSourceType,
+)
+
+if TYPE_CHECKING:
+    from gobby.storage.database import DatabaseProtocol
+
+logger = logging.getLogger(__name__)
+
+
+class SkillManager:
+    """Coordinates skill storage and search operations.
+
+    This class provides a unified interface for skill management,
+    wiring together:
+    - LocalSkillManager for persistent storage
+    - SkillSearch for TF-IDF based search
+    - SkillChangeNotifier for automatic reindex tracking
+
+    Example usage:
+        ```python
+        from gobby.skills.manager import SkillManager
+        from gobby.storage.database import LocalDatabase
+
+        db = LocalDatabase("gobby-hub.db")
+        manager = SkillManager(db)
+
+        # Create a skill
+        skill = manager.create_skill(
+            name="commit-message",
+            description="Generate commit messages",
+            content="# Instructions...",
+        )
+
+        # Search for skills
+        manager.reindex()
+        results = manager.search("git commit")
+        ```
+    """
+
+    def __init__(
+        self,
+        db: DatabaseProtocol,
+        project_id: str | None = None,
+    ):
+        """Initialize the skill manager.
+
+        Args:
+            db: Database connection for storage
+            project_id: Optional default project scope
+        """
+        self._project_id = project_id
+
+        # Set up change notifier
+        self._notifier = SkillChangeNotifier()
+        self._notifier.add_listener(self._on_skill_change)
+
+        # Initialize storage with notifier
+        self._storage = LocalSkillManager(db, notifier=self._notifier)
+
+        # Initialize search
+        self._search = SkillSearch()
+
+    @property
+    def storage(self) -> LocalSkillManager:
+        """Get the storage manager."""
+        return self._storage
+
+    @property
+    def search(self) -> SkillSearch:
+        """Get the search instance."""
+        return self._search
+
+    def _on_skill_change(self, event: ChangeEvent) -> None:
+        """Handle skill change events for search tracking.
+
+        Args:
+            event: The change event
+        """
+        if event.event_type == "create":
+            # Get the full skill for search
+            try:
+                skill = self._storage.get_skill(event.skill_id)
+                try:
+                    self._search.add_skill(skill)
+                except Exception as e:
+                    logger.error(
+                        f"Failed to add skill to search index "
+                        f"(event={event.event_type}, skill_id={event.skill_id}): {e}"
+                    )
+            except ValueError as e:
+                logger.debug(
+                    f"Failed to get skill for {event.event_type} event "
+                    f"(skill_id={event.skill_id}): {e}"
+                )
+        elif event.event_type == "update":
+            try:
+                skill = self._storage.get_skill(event.skill_id)
+                try:
+                    self._search.update_skill(skill)
+                except Exception as e:
+                    logger.error(
+                        f"Failed to update skill in search index "
+                        f"(event={event.event_type}, skill_id={event.skill_id}): {e}"
+                    )
+            except ValueError as e:
+                logger.debug(
+                    f"Failed to get skill for {event.event_type} event "
+                    f"(skill_id={event.skill_id}): {e}"
+                )
+        elif event.event_type == "delete":
+            try:
+                self._search.remove_skill(event.skill_id)
+            except Exception as e:
+                logger.error(
+                    f"Failed to remove skill from search index "
+                    f"(event={event.event_type}, skill_id={event.skill_id}): {e}"
+                )
+
+    # --- CRUD Operations ---
+
+    def create_skill(
+        self,
+        name: str,
+        description: str,
+        content: str,
+        version: str | None = None,
+        license: str | None = None,
+        compatibility: str | None = None,
+        allowed_tools: list[str] | None = None,
+        metadata: dict[str, Any] | None = None,
+        source_path: str | None = None,
+        source_type: SkillSourceType | None = None,
+        source_ref: str | None = None,
+        enabled: bool = True,
+        project_id: str | None = None,
+    ) -> Skill:
+        """Create a new skill.
+
+        Args:
+            name: Skill name
+            description: Skill description
+            content: Markdown content
+            version: Optional version string
+            license: Optional license identifier
+            compatibility: Optional compatibility notes
+            allowed_tools: Optional allowed tool patterns
+            metadata: Optional metadata (includes skillport/gobby namespaces)
+            source_path: Original source path
+            source_type: Source type
+            source_ref: Git ref for updates
+            enabled: Whether skill is active
+            project_id: Project scope (uses default if not specified)
+
+        Returns:
+            The created Skill
+        """
+        return self._storage.create_skill(
+            name=name,
+            description=description,
+            content=content,
+            version=version,
+            license=license,
+            compatibility=compatibility,
+            allowed_tools=allowed_tools,
+            metadata=metadata,
+            source_path=source_path,
+            source_type=source_type,
+            source_ref=source_ref,
+            enabled=enabled,
+            project_id=project_id or self._project_id,
+        )
+
+    def get_skill(self, skill_id: str) -> Skill:
+        """Get a skill by ID.
+
+        Args:
+            skill_id: The skill ID
+
+        Returns:
+            The Skill
+
+        Raises:
+            ValueError: If not found
+        """
+        return self._storage.get_skill(skill_id)
+
+    def get_by_name(
+        self,
+        name: str,
+        project_id: str | None = None,
+    ) -> Skill | None:
+        """Get a skill by name.
+
+        Args:
+            name: Skill name
+            project_id: Project scope (uses default if not specified)
+
+        Returns:
+            The Skill if found, None otherwise
+        """
+        return self._storage.get_by_name(
+            name,
+            project_id=project_id or self._project_id,
+        )
+
+    def update_skill(
+        self,
+        skill_id: str,
+        name: str | None = None,
+        description: str | None = None,
+        content: str | None = None,
+        **kwargs: Any,
+    ) -> Skill:
+        """Update a skill.
+
+        Args:
+            skill_id: ID of the skill to update
+            name: New name (optional)
+            description: New description (optional)
+            content: New content (optional)
+            **kwargs: Additional fields to update
+
+        Returns:
+            The updated Skill
+        """
+        return self._storage.update_skill(
+            skill_id=skill_id,
+            name=name,
+            description=description,
+            content=content,
+            **kwargs,
+        )
+
+    def delete_skill(self, skill_id: str) -> bool:
+        """Delete a skill.
+
+        Args:
+            skill_id: ID of the skill to delete
+
+        Returns:
+            True if deleted, False if not found
+        """
+        return self._storage.delete_skill(skill_id)
+
+    def list_skills(
+        self,
+        project_id: str | None = None,
+        enabled: bool | None = None,
+        category: str | None = None,
+        limit: int = 50,
+        offset: int = 0,
+        include_global: bool = True,
+    ) -> list[Skill]:
+        """List skills with optional filtering.
+
+        Args:
+            project_id: Filter by project (uses default if not specified)
+            enabled: Filter by enabled state
+            category: Filter by category
+            limit: Maximum results
+            offset: Results to skip
+            include_global: Include global skills
+
+        Returns:
+            List of matching Skills
+        """
+        return self._storage.list_skills(
+            project_id=project_id or self._project_id,
+            enabled=enabled,
+            category=category,
+            limit=limit,
+            offset=offset,
+            include_global=include_global,
+        )
+
+    # --- Search Operations ---
+
+    def search_skills(
+        self,
+        query: str,
+        top_k: int = 10,
+        filters: SearchFilters | None = None,
+    ) -> list[SkillSearchResult]:
+        """Search for skills.
+
+        Args:
+            query: Search query
+            top_k: Maximum results
+            filters: Optional filters
+
+        Returns:
+            List of search results
+        """
+        return self._search.search(query, top_k=top_k, filters=filters)
+
+    def reindex(self, batch_size: int = 1000) -> None:
+        """Rebuild the search index from storage.
+
+        Args:
+            batch_size: Number of skills to fetch per batch (default: 1000)
+        """
+        all_skills: list[Skill] = []
+        offset = 0
+
+        # Paginate through all skills to avoid truncation
+        while True:
+            batch = self._storage.list_skills(
+                project_id=self._project_id,
+                include_global=True,
+                limit=batch_size,
+                offset=offset,
+            )
+            if not batch:
+                break
+            all_skills.extend(batch)
+            if len(batch) < batch_size:
+                # Last batch, no more results
+                break
+            offset += batch_size
+
+        self._search.index_skills(all_skills)
+
+    def needs_reindex(self) -> bool:
+        """Check if search index needs rebuilding.
+
+        Returns:
+            True if reindex() should be called
+        """
+        return self._search.needs_reindex()
+
+    # --- Core Skills ---
+
+    def list_core_skills(self, project_id: str | None = None) -> list[Skill]:
+        """List skills with alwaysApply=true.
+
+        Core skills are automatically included in agent prompts.
+
+        Args:
+            project_id: Project scope (uses default if not specified)
+
+        Returns:
+            List of core skills
+        """
+        return self._storage.list_core_skills(project_id=project_id or self._project_id)
+
+    # --- Utility ---
+
+    def count_skills(
+        self,
+        project_id: str | None = None,
+        enabled: bool | None = None,
+    ) -> int:
+        """Count skills matching criteria.
+
+        Args:
+            project_id: Project scope
+            enabled: Filter by enabled state
+
+        Returns:
+            Number of matching skills
+        """
+        return self._storage.count_skills(
+            project_id=project_id or self._project_id,
+            enabled=enabled,
+        )

gobby/skills/parser.py

@@ -0,0 +1,286 @@
+"""YAML frontmatter parser for SKILL.md files.
+
+This module parses skill files following the Agent Skills specification format:
+- YAML frontmatter delimited by ---
+- Markdown content body
+
+Example SKILL.md format:
+```markdown
+---
+name: commit-message
+description: Generate conventional commit messages
+license: MIT
+compatibility: Requires git CLI
+metadata:
+  author: anthropic
+  version: "1.0"
+  skillport:
+    category: git
+    tags: [git, commits]
+    alwaysApply: false
+  gobby:
+    triggers: ["/commit"]
+allowed-tools: Bash(git:*)
+---
+
+# Commit Message Generator
+
+Instructions for the skill...
+```
+"""
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+# Pattern to extract YAML frontmatter (content between --- delimiters)
+# Allows empty frontmatter (---\n---) or content between delimiters
+# Supports both LF (\n) and CRLF (\r\n) line endings
+FRONTMATTER_PATTERN = re.compile(
+    r"^---[ \t]*\r?\n(.*?)^---[ \t]*\r?\n?",
+    re.DOTALL | re.MULTILINE,
+)
+
+
+@dataclass
+class ParsedSkill:
+    """Parsed skill data from a SKILL.md file.
+
+    Attributes:
+        name: Skill name (required)
+        description: Skill description (required)
+        content: Markdown body content
+        version: Version string (from metadata.version or top-level)
+        license: License identifier
+        compatibility: Compatibility notes
+        allowed_tools: List of allowed tool patterns
+        metadata: Full metadata dict (includes skillport/gobby namespaces)
+        source_path: Path the skill was loaded from
+        source_type: Source type (local, github, zip, etc.)
+        source_ref: Git ref for GitHub imports
+        scripts: List of script file paths (relative to skill dir)
+        references: List of reference file paths (relative to skill dir)
+        assets: List of asset file paths (relative to skill dir)
+    """
+
+    name: str
+    description: str
+    content: str
+    version: str | None = None
+    license: str | None = None
+    compatibility: str | None = None
+    allowed_tools: list[str] | None = None
+    metadata: dict[str, Any] | None = None
+    source_path: str | None = None
+    source_type: str | None = None
+    source_ref: str | None = None
+    scripts: list[str] | None = None
+    references: list[str] | None = None
+    assets: list[str] | None = None
+
+    def get_category(self) -> str | None:
+        """Get category from top-level or metadata.skillport.category."""
+        if not self.metadata:
+            return None
+        # Check top-level first (from frontmatter)
+        result = self.metadata.get("category")
+        if result is not None:
+            return str(result)
+        # Fall back to nested skillport.category
+        skillport = self.metadata.get("skillport", {})
+        result = skillport.get("category")
+        return str(result) if result is not None else None
+
+    def get_tags(self) -> list[str]:
+        """Get tags from metadata.skillport.tags."""
+        if not self.metadata:
+            return []
+        skillport = self.metadata.get("skillport", {})
+        tags = skillport.get("tags", [])
+        if isinstance(tags, list):
+            return tags
+        if isinstance(tags, str):
+            return [tags]
+        return []
+
+    def is_always_apply(self) -> bool:
+        """Check if this is a core skill (alwaysApply=true).
+
+        Supports both top-level alwaysApply and nested metadata.skillport.alwaysApply.
+        Top-level takes precedence.
+        """
+        if not self.metadata:
+            return False
+        # Check top-level first (from frontmatter)
+        top_level = self.metadata.get("alwaysApply")
+        if top_level is not None:
+            return bool(top_level)
+        # Fall back to nested skillport.alwaysApply
+        skillport = self.metadata.get("skillport", {})
+        return bool(skillport.get("alwaysApply", False))
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary representation."""
+        return {
+            "name": self.name,
+            "description": self.description,
+            "content": self.content,
+            "version": self.version,
+            "license": self.license,
+            "compatibility": self.compatibility,
+            "allowed_tools": self.allowed_tools,
+            "metadata": self.metadata,
+            "source_path": self.source_path,
+            "source_type": self.source_type,
+            "source_ref": self.source_ref,
+            "scripts": self.scripts,
+            "references": self.references,
+            "assets": self.assets,
+        }
+
+
+class SkillParseError(Exception):
+    """Error parsing a skill file."""
+
+    def __init__(self, message: str, path: str | None = None):
+        self.path = path
+        super().__init__(f"{message}" + (f" in {path}" if path else ""))
+
+
+def parse_frontmatter(text: str) -> tuple[dict[str, Any], str]:
+    """Parse YAML frontmatter from text.
+
+    Args:
+        text: Full text content with frontmatter
+
+    Returns:
+        Tuple of (frontmatter dict, content body)
+
+    Raises:
+        SkillParseError: If frontmatter is missing or invalid
+    """
+    match = FRONTMATTER_PATTERN.match(text)
+    if not match:
+        raise SkillParseError("Missing or invalid YAML frontmatter (must start with ---)")
+
+    frontmatter_yaml = match.group(1)
+    content = text[match.end() :].strip()
+
+    try:
+        frontmatter = yaml.safe_load(frontmatter_yaml)
+    except yaml.YAMLError as e:
+        raise SkillParseError(f"Invalid YAML in frontmatter: {e}") from e
+
+    if frontmatter is None:
+        frontmatter = {}
+
+    if not isinstance(frontmatter, dict):
+        raise SkillParseError("Frontmatter must be a YAML mapping")
+
+    return frontmatter, content
+
+
+def parse_skill_text(text: str, source_path: str | None = None) -> ParsedSkill:
+    """Parse a skill from text content.
+
+    Args:
+        text: Full skill file content (frontmatter + markdown)
+        source_path: Optional path for error messages
+
+    Returns:
+        ParsedSkill with extracted data
+
+    Raises:
+        SkillParseError: If parsing fails or required fields missing
+    """
+    try:
+        frontmatter, content = parse_frontmatter(text)
+    except SkillParseError as e:
+        # Create a new exception with the path included in the message
+        raise SkillParseError(str(e), path=source_path) from e
+
+    # Extract required fields
+    name = frontmatter.get("name")
+    if not name:
+        raise SkillParseError("Missing required field: name", source_path)
+
+    description = frontmatter.get("description")
+    if not description:
+        raise SkillParseError("Missing required field: description", source_path)
+
+    # Extract optional fields
+    license_str = frontmatter.get("license")
+    compatibility = frontmatter.get("compatibility")
+
+    # Handle allowed-tools (can be string or list)
+    allowed_tools_raw = frontmatter.get("allowed-tools") or frontmatter.get("allowed_tools")
+    allowed_tools: list[str] | None = None
+    if allowed_tools_raw:
+        if isinstance(allowed_tools_raw, str):
+            # Single tool or comma-separated
+            allowed_tools = [t.strip() for t in allowed_tools_raw.split(",")]
+        elif isinstance(allowed_tools_raw, list):
+            allowed_tools = [str(t) for t in allowed_tools_raw]
+
+    # Extract metadata (may contain version, skillport, gobby namespaces)
+    metadata = frontmatter.get("metadata")
+
+    # Handle top-level alwaysApply and category by including them in metadata
+    # This allows both top-level and nested formats to work
+    top_level_always_apply = frontmatter.get("alwaysApply")
+    top_level_category = frontmatter.get("category")
+
+    if top_level_always_apply is not None or top_level_category is not None:
+        if metadata is None:
+            metadata = {}
+        # Store at top level of metadata (not nested in skillport)
+        if top_level_always_apply is not None:
+            metadata["alwaysApply"] = top_level_always_apply
+        if top_level_category is not None:
+            metadata["category"] = top_level_category
+
+    # Version can be at top level or in metadata
+    version = frontmatter.get("version")
+    if version is None and metadata and isinstance(metadata, dict):
+        version = metadata.get("version")
+
+    # Convert version to string if it's a number (e.g., 1.0 parsed as float)
+    if version is not None:
+        version = str(version)
+
+    return ParsedSkill(
+        name=name,
+        description=description,
+        content=content,
+        version=version,
+        license=license_str,
+        compatibility=compatibility,
+        allowed_tools=allowed_tools,
+        metadata=metadata,
+        source_path=source_path,
+    )
+
+
+def parse_skill_file(path: str | Path) -> ParsedSkill:
+    """Parse a skill from a file path.
+
+    Args:
+        path: Path to SKILL.md file
+
+    Returns:
+        ParsedSkill with extracted data
+
+    Raises:
+        FileNotFoundError: If file doesn't exist
+        SkillParseError: If parsing fails (propagated from parse_skill_text)
+    """
+    path = Path(path)
+
+    if not path.exists():
+        raise FileNotFoundError(f"Skill file not found: {path}")
+
+    text = path.read_text(encoding="utf-8")
+    return parse_skill_text(text, source_path=str(path))