code-muse 0.0.1__py3-none-any.whl

code_muse/plugins/agent_skills/config.py

@@ -0,0 +1,176 @@
+"""Plugin-level config helpers for agent_skills."""
+
+import json
+import logging
+from pathlib import Path
+
+from code_muse.config import get_value, set_value
+
+logger = logging.getLogger(__name__)
+
+
+def get_skill_directories() -> list[Path]:
+    """Get configured skill directories.
+
+    Returns:
+        List of skill directory paths from configuration.
+        Reads from muse.cfg [muse] section under 'skill_directories' key.
+        Default: ['~/.muse/skills', './.muse/skills', './skills']
+
+    The directories are stored as a JSON list in the config.
+    """
+    # Try to read from config first
+    config_value = get_value("skill_directories")
+
+    if config_value:
+        try:
+            # Parse as JSON
+            directories = json.loads(config_value)
+            # Ensure it's a list
+            if isinstance(directories, list):
+                return [Path(d) for d in directories]
+        except json.JSONDecodeError as e:
+            logger.error(f"Failed to parse skill_directories config: {e}")
+
+    # Fallback to defaults
+    home_skills = Path.home() / ".muse" / "skills"
+    project_config_skills = Path.cwd() / ".muse" / "skills"
+    local_skills = Path.cwd() / "skills"
+    return [
+        home_skills,
+        project_config_skills,
+        local_skills,
+    ]
+
+
+def add_skill_directory(path: str | Path) -> bool:
+    """Add a directory to the skills search path.
+
+    Args:
+        path: Path to add to the skill directories list.
+
+    Returns:
+        True if the directory was added successfully, False otherwise.
+    """
+    directories = [Path(d) for d in get_skill_directories()]
+    path = Path(path)
+
+    # Check if already exists
+    if path in directories:
+        logger.info(f"Skill directory already exists: {path}")
+        return False
+
+    # Add the new directory
+    directories.append(path)
+
+    try:
+        # Save back to config as JSON
+        set_value("skill_directories", json.dumps([str(d) for d in directories]))
+        logger.info(f"Added skill directory: {path}")
+        return True
+    except Exception as e:
+        logger.error(f"Failed to add skill directory: {e}")
+        return False
+
+
+def remove_skill_directory(path: str | Path) -> bool:
+    """Remove a directory from the skills search path.
+
+    Args:
+        path: Path to remove from the skill directories list.
+
+    Returns:
+        True if the directory was removed successfully, False otherwise.
+    """
+    directories = [Path(d) for d in get_skill_directories()]
+    path = Path(path)
+
+    # Check if exists
+    if path not in directories:
+        logger.info(f"Skill directory not found: {path}")
+        return False
+
+    # Remove the directory
+    directories.remove(path)
+
+    try:
+        # Save back to config as JSON
+        set_value("skill_directories", json.dumps([str(d) for d in directories]))
+        logger.info(f"Removed skill directory: {path}")
+        return True
+    except Exception as e:
+        logger.error(f"Failed to remove skill directory: {e}")
+        return False
+
+
+def get_skills_enabled() -> bool:
+    """Check if skills integration is globally enabled.
+
+    Returns:
+        True if skills are globally enabled, False otherwise.
+        Reads from 'skills_enabled' config key (default: True).
+    """
+    cfg_val = get_value("skills_enabled")
+    if cfg_val is None:
+        return True  # Enabled by default
+    return str(cfg_val).strip().lower() in {"1", "true", "yes", "on"}
+
+
+def set_skills_enabled(enabled: bool) -> None:
+    """Enable or disable skills integration globally.
+
+    Args:
+        enabled: True to enable, False to disable.
+    """
+    set_value("skills_enabled", "true" if enabled else "false")
+    logger.info(f"Skills integration {'enabled' if enabled else 'disabled'}")
+
+
+def get_disabled_skills() -> set[str]:
+    """Get set of explicitly disabled skill names.
+
+    Returns:
+        Set of skill names that are disabled.
+        Reads from 'disabled_skills' config key as a JSON list.
+    """
+    config_value = get_value("disabled_skills")
+
+    if config_value:
+        try:
+            # Parse as JSON
+            disabled_list = json.loads(config_value)
+            # Ensure it's a list and convert to set
+            if isinstance(disabled_list, list):
+                return set(disabled_list)
+        except json.JSONDecodeError as e:
+            logger.error(f"Failed to parse disabled_skills config: {e}")
+
+    return set()
+
+
+def set_skill_disabled(skill_name: str, disabled: bool) -> None:
+    """Disable or re-enable a specific skill.
+
+    Args:
+        skill_name: Name of the skill to disable/enable.
+        disabled: True to disable, False to enable.
+    """
+    disabled_skills = get_disabled_skills()
+
+    if disabled:
+        # Add to disabled set
+        if skill_name in disabled_skills:
+            logger.info(f"Skill already disabled: {skill_name}")
+            return
+        disabled_skills.add(skill_name)
+        logger.info(f"Disabled skill: {skill_name}")
+    else:
+        # Remove from disabled set
+        if skill_name not in disabled_skills:
+            logger.info(f"Skill already enabled: {skill_name}")
+            return
+        disabled_skills.remove(skill_name)
+        logger.info(f"Enabled skill: {skill_name}")
+
+    # Save back to config as JSON
+    set_value("disabled_skills", json.dumps(list(disabled_skills)))

code_muse/plugins/agent_skills/discovery.py

@@ -0,0 +1,309 @@
+"""Skill discovery - scans directories for valid skills.
+
+Includes safety checks for symlink escapes, hidden directories,
+SKILL.md size validation, and executable file awareness.
+"""
+
+import contextlib
+import logging
+import stat
+from dataclasses import dataclass
+from pathlib import Path
+
+from code_muse.plugins.agent_skills.config import get_skill_directories
+
+logger = logging.getLogger(__name__)
+
+# Max SKILL.md file size before we refuse to read (256 KiB)
+MAX_SKILL_MD_BYTES = 256 * 1024
+
+# Cap for skill content injected into model context (chars)
+SKILL_CONTEXT_CAP = 64_000
+
+
+@dataclass
+class SkillInfo:
+    """Basic skill information from discovery."""
+
+    name: str
+    path: Path
+    has_skill_md: bool
+    skill_md_size: int | None = None
+    skill_md_hash: str | None = None
+    source: str | None = None
+    trust: str | None = None  # "builtin" | "user" | None
+
+
+# Global cache for discovered skills
+_skill_cache: list[SkillInfo | None] = None
+
+
+def _is_symlink_escape(child: Path, parent: Path) -> bool:
+    """Return True if *child* resolves outside *parent* (symlink escape)."""
+    try:
+        child.resolve().relative_to(parent.resolve())
+        return False
+    except ValueError:
+        return True
+
+
+def _has_unexpected_executables(skill_dir: Path) -> bool:
+    """Return True if *skill_dir* contains unexpected executable files.
+
+    We expect only .md, .txt, .json, .yaml, .yml, .py, .toml files in
+    skill directories. Anything with the execute bit set (beyond
+    directory traversal) is flagged.
+    """
+    safe_extensions = {
+        ".md",
+        ".txt",
+        ".json",
+        ".yaml",
+        ".yml",
+        ".py",
+        ".toml",
+        ".cfg",
+        ".ini",
+        ".rst",
+        ".html",
+        ".css",
+        ".js",
+    }
+    try:
+        for item in skill_dir.iterdir():
+            if not item.is_file():
+                continue
+            # Skip symlinks that escape
+            if item.is_symlink() and _is_symlink_escape(item, skill_dir):
+                return True
+            # Check for executable bit on non-standard files
+            if item.suffix.lower() not in safe_extensions:
+                try:
+                    mode = item.stat().st_mode
+                    if mode & (stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH):
+                        logger.warning(
+                            "Unexpected executable file in skill dir %s: %s",
+                            skill_dir.name,
+                            item.name,
+                        )
+                        return True
+                except OSError:
+                    pass
+    except OSError:
+        pass
+    return False
+
+
+def get_default_skill_directories() -> list[Path]:
+    """Return default directories to scan for skills.
+
+    Returns:
+        - ~/.muse/skills (user skills)
+        - ./.muse/skills (project config skills)
+        - ./skills (project skills)
+    """
+    return [
+        Path.home() / ".muse" / "skills",
+        Path.cwd() / ".muse" / "skills",
+        Path.cwd() / "skills",
+    ]
+
+
+def is_valid_skill_directory(path: Path) -> bool:
+    """Check if a directory contains a valid SKILL.md file.
+
+    Also validates that SKILL.md is not oversized and that
+    the directory does not contain unexpected executables.
+
+    Args:
+        path: Directory path to check.
+
+    Returns:
+        True if the directory is a valid skill directory, False otherwise.
+    """
+    if not path.is_dir():
+        return False
+
+    skill_md_path = path / "SKILL.md"
+    if not skill_md_path.is_file():
+        return False
+
+    # Check for symlink escape on SKILL.md
+    if _is_symlink_escape(skill_md_path, path):
+        logger.warning("SKILL.md in %s is a symlink escape, skipping", path.name)
+        return False
+
+    # Validate SKILL.md size before we ever read it
+    try:
+        size = skill_md_path.stat().st_size
+        if size > MAX_SKILL_MD_BYTES:
+            logger.warning(
+                "SKILL.md in %s is too large (%d bytes, max %d), skipping",
+                path.name,
+                size,
+                MAX_SKILL_MD_BYTES,
+            )
+            return False
+    except OSError:
+        return False
+
+    # Check for unexpected executable files
+    if _has_unexpected_executables(path):
+        logger.warning(
+            "Skill directory %s contains unexpected executable files, skipping",
+            path.name,
+        )
+        return False
+
+    return True
+
+
+def _compute_skill_md_hash(skill_md_path: Path) -> str | None:
+    """Compute SHA-256 hash of a SKILL.md file."""
+    import hashlib
+
+    try:
+        content = skill_md_path.read_bytes()
+        return hashlib.sha256(content).hexdigest()
+    except OSError:
+        return None
+
+
+def _classify_skill_source(skill_dir: Path) -> str:
+    """Classify a skill directory as 'builtin' or 'user'."""
+    home_skills = Path.home() / ".muse" / "skills"
+    try:
+        skill_dir.resolve().relative_to(home_skills.resolve())
+        return "user"
+    except ValueError:
+        pass
+    # Check if it's under CWD
+    try:
+        skill_dir.resolve().relative_to(Path.cwd().resolve())
+        return "project"
+    except ValueError:
+        pass
+    return "unknown"
+
+
+def discover_skills(directories: list[Path | None] = None) -> list[SkillInfo]:
+    """Scan directories for valid skills.
+
+    Args:
+        directories: Directories to scan. If None, uses configured
+                     directories (which includes user-added ones from /skills menu).
+
+    Returns:
+        List of discovered SkillInfo objects.
+    """
+    global _skill_cache
+
+    if directories is None:
+        # Use configured directories (respects user-added dirs from /skills menu)
+        # then merge with defaults to ensure we always check the standard locations
+        configured = [Path(d) for d in get_skill_directories()]
+        defaults = get_default_skill_directories()
+        # Merge: configured first, then any defaults not already covered
+        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] = []
+
+    for directory in directories:
+        if not directory.exists():
+            logger.debug("Skill directory does not exist: %s", directory)
+            continue
+
+        if not directory.is_dir():
+            logger.warning("Skill path is not a directory: %s", directory)
+            continue
+
+        # Scan subdirectories within the skill directory
+        for skill_dir in directory.iterdir():
+            if not skill_dir.is_dir():
+                continue
+
+            # Skip hidden directories
+            if skill_dir.name.startswith(".") or skill_dir.name.startswith("_"):
+                continue
+
+            # Skip symlink escapes
+            if _is_symlink_escape(skill_dir, directory):
+                logger.warning(
+                    "Skipping skill dir %s: symlink escape from %s",
+                    skill_dir.name,
+                    directory,
+                )
+                continue
+
+            has_skill_md = is_valid_skill_directory(skill_dir)
+
+            # Compute metadata for valid skills
+            skill_md_size = None
+            skill_md_hash = None
+            if has_skill_md:
+                skill_md_path = skill_dir / "SKILL.md"
+                with contextlib.suppress(OSError):
+                    skill_md_size = skill_md_path.stat().st_size
+                skill_md_hash = _compute_skill_md_hash(skill_md_path)
+
+            source = _classify_skill_source(skill_dir)
+            # Built-in skills from the package are always trusted
+            trust = "builtin" if source == "unknown" else source
+
+            skill_info = SkillInfo(
+                name=skill_dir.name,
+                path=skill_dir,
+                has_skill_md=has_skill_md,
+                skill_md_size=skill_md_size,
+                skill_md_hash=skill_md_hash,
+                source=source,
+                trust=trust,
+            )
+            discovered_skills.append(skill_info)
+
+            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
+                )
+
+    # Update cache
+    _skill_cache = discovered_skills
+
+    logger.info(
+        "Discovered %d skills from %d directories",
+        len(discovered_skills),
+        len(directories),
+    )
+    return discovered_skills
+
+
+def refresh_skill_cache() -> list[SkillInfo]:
+    """Force re-discovery of all skills.
+
+    This clears the cache and performs a fresh scan of all default
+    skill directories.
+
+    Returns:
+        List of freshly discovered SkillInfo objects.
+    """
+    global _skill_cache
+    _skill_cache = None
+    return discover_skills()
+
+
+def cap_skill_content(content: str, cap: int = SKILL_CONTEXT_CAP) -> str:
+    """Cap skill content to prevent model-context blowup.
+
+    If content exceeds *cap* characters, it is truncated with a marker.
+    """
+    if len(content) <= cap:
+        return content
+    return content[:cap] + "\n... [skill content truncated]"