python-skills 1.0.0__py3-none-any.whl

python_skills/installer.py

@@ -0,0 +1,163 @@
+"""Installer orchestration for python-skills."""
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from python_skills.adapters import get_adapter
+from python_skills.adapters.base import InstallResult
+from python_skills.config import InstallConfig, Scope, Target, get_adapter_capabilities
+from python_skills.detector import DetectionSummary, EnvironmentDetector
+from python_skills.skills.registry import get_registry
+from python_skills.state import LockManager
+
+
+@dataclass
+class InstallPlan:
+    """Plan for installation."""
+    targets: dict[Target, Scope]
+    dry_run: bool = False
+
+
+class SkillInstaller:
+    """Orchestrates installation of python-skills across multiple agents."""
+
+    def __init__(self, project_root: Path, config: InstallConfig):
+        self.project_root = Path(project_root).resolve()
+        self.config = config
+        self.detector = EnvironmentDetector(self.project_root)
+        self.skills_registry = get_registry()
+        self.lock_manager = LockManager(self.project_root)
+
+    def detect_environments(self) -> DetectionSummary:
+        """Detect all AI coding agent environments."""
+        return self.detector.detect_all()
+
+    def plan_installation(self, targets: list[Target] | None = None,
+                          scope: Scope = Scope.PROJECT,
+                          auto: bool = False) -> InstallPlan:
+        """Create installation plan based on detection and user selection."""
+        detection = self.detect_environments()
+        plan_targets = {}
+
+        if auto:
+            for target_name, result in detection.targets.items():
+                target = Target(target_name)
+                caps = get_adapter_capabilities(target)
+                if result.project_config_detected or result.application_detected:
+                    if (scope == Scope.PROJECT and caps.supports_project) or \
+                       (scope == Scope.GLOBAL and caps.supports_global):
+                        plan_targets[target] = scope
+        elif targets:
+            for target in targets:
+                caps = get_adapter_capabilities(target)
+                if scope == Scope.PROJECT and caps.supports_project:
+                    plan_targets[target] = scope
+                elif scope == Scope.GLOBAL and caps.supports_global:
+                    plan_targets[target] = scope
+                else:
+                    raise ValueError(f"Target {target} does not support scope {scope}")
+        else:
+            for target_name, result in detection.targets.items():
+                target = Target(target_name)
+                if result.project_config_detected:
+                    caps = get_adapter_capabilities(target)
+                    if caps.supports_project:
+                        plan_targets[target] = scope
+
+        return InstallPlan(targets=plan_targets, dry_run=self.config.dry_run)
+
+    def execute_install(self, plan: InstallPlan) -> dict[Target, InstallResult]:
+        """Execute installation according to plan."""
+        results = {}
+
+        for target, scope in plan.targets.items():
+            try:
+                adapter = get_adapter(target, self.project_root, self.skills_registry, self.lock_manager, self.config)
+                result = adapter.install(scope=scope.value, dry_run=plan.dry_run)
+                results[target] = result
+
+                status = "PASS" if result.success else "FAIL"
+                print(f"  {target.value}: {status} ({len(result.files_created)} files, {len(result.errors)} errors)")
+                if result.errors:
+                    for err in result.errors:
+                        print(f"    ERROR: {err}")
+                if result.warnings:
+                    for warn in result.warnings:
+                        print(f"    WARNING: {warn}")
+            except Exception as e:
+                results[target] = InstallResult(
+                    success=False, target=target.value, scope=scope.value,
+                    errors=[str(e)]
+                )
+                print(f"  {target.value}: FAIL ({e})")
+
+        return results
+
+    def run_sync(self, scope: Scope = Scope.PROJECT,
+                 targets: list[Target] | None = None,
+                 dry_run: bool = False) -> dict[Target, any]:
+        """Run sync across targets."""
+
+        if targets is None:
+            targets = [Target(t) for t in self.lock_manager.get_all_targets().keys()
+                       if t in [t.value for t in Target]]
+
+        results = {}
+        for target in targets:
+            try:
+                adapter = get_adapter(target, self.project_root, self.skills_registry, self.lock_manager, self.config)
+                result = adapter.sync(scope=scope.value, dry_run=dry_run)
+                results[target] = result
+
+                status = "PASS" if result.success else "FAIL"
+                print(f"  {target.value}: {status} ({len(result.added)} added, {len(result.modified)} modified, {len(result.removed)} removed)")
+                if result.errors:
+                    for err in result.errors:
+                        print(f"    ERROR: {err}")
+            except Exception as e:
+                print(f"  {target.value}: FAIL ({e})")
+
+        return results
+
+    def run_uninstall(self, scope: Scope = Scope.PROJECT,
+                      targets: list[Target] | None = None,
+                      dry_run: bool = False) -> dict[Target, any]:
+        """Run uninstall across targets."""
+
+        if targets is None:
+            targets = [Target(t) for t in self.lock_manager.get_all_targets().keys()
+                       if t in [t.value for t in Target]]
+
+        results = {}
+        for target in targets:
+            try:
+                adapter = get_adapter(target, self.project_root, self.skills_registry, self.lock_manager, self.config)
+                result = adapter.uninstall(scope=scope.value, dry_run=dry_run)
+                results[target] = result
+
+                status = "PASS" if result.success else "FAIL"
+                print(f"  {target.value}: {status} ({len(result.files_removed)} files)")
+                if result.errors:
+                    for err in result.errors:
+                        print(f"    ERROR: {err}")
+            except Exception as e:
+                print(f"  {target.value}: FAIL ({e})")
+
+        return results
+
+    def get_status(self, scope: Scope = Scope.PROJECT) -> dict[Target, any]:
+        """Get installation status for all targets."""
+
+        results = {}
+        for target in Target:
+            try:
+                adapter = get_adapter(target, self.project_root, self.skills_registry, self.lock_manager, self.config)
+                result = adapter.status(scope=scope.value)
+                results[target] = result
+
+                status = "Installed" if result.installed else "Not installed"
+                print(f"  {target.value}: {status} ({len(result.files)} files)")
+            except Exception as e:
+                print(f"  {target.value}: Error ({e})")
+
+        return results

python_skills/markers.py

@@ -0,0 +1,115 @@
+"""Ownership marker utilities for generated content."""
+
+
+
+# Standard ownership markers
+BEGIN_MARKER = "<!-- BEGIN PYTHON-SKILLS MANAGED -->"
+END_MARKER = "<!-- END PYTHON-SKILLS MANAGED -->"
+
+# Format-specific markers
+MARKERS = {
+    "md": (BEGIN_MARKER, END_MARKER),
+    "mdc": (BEGIN_MARKER, END_MARKER),
+    "mdx": (BEGIN_MARKER, END_MARKER),
+    "txt": (BEGIN_MARKER, END_MARKER),
+    "yaml": ("# PYTHON-SKILLS MANAGED", "# END PYTHON-SKILLS MANAGED"),
+    "yml": ("# PYTHON-SKILLS MANAGED", "# END PYTHON-SKILLS MANAGED"),
+    "json": ("// PYTHON-SKILLS MANAGED", "// END PYTHON-SKILLS MANAGED"),
+    "py": ("# PYTHON-SKILLS MANAGED", "# END PYTHON-SKILLS MANAGED"),
+    "js": ("// PYTHON-SKILLS MANAGED", "// END PYTHON-SKILLS MANAGED"),
+    "ts": ("// PYTHON-SKILLS MANAGED", "// END PYTHON-SKILLS MANAGED"),
+}
+
+
+def get_markers(file_path: str) -> tuple[str, str]:
+    """Get ownership markers for a file type."""
+    ext = file_path.split(".")[-1].lower() if "." in file_path else "md"
+    return MARKERS.get(ext, (BEGIN_MARKER, END_MARKER))
+
+
+def wrap_managed_content(content: str, file_path: str) -> str:
+    """Wrap content with ownership markers."""
+    begin, end = get_markers(file_path)
+    return f"{begin}\n{content}\n{end}"
+
+
+def extract_managed_region(content: str, file_path: str) -> str | None:
+    """Extract content between ownership markers."""
+    begin, end = get_markers(file_path)
+
+    start_idx = content.find(begin)
+    if start_idx == -1:
+        return None
+
+    start_idx += len(begin)
+    end_idx = content.find(end, start_idx)
+    if end_idx == -1:
+        return None
+
+    return content[start_idx:end_idx]
+
+
+def replace_managed_region(content: str, new_content: str, file_path: str) -> tuple[str, bool]:
+    """
+    Replace content between ownership markers.
+    
+    Returns:
+        Tuple of (new_content, was_replaced)
+    """
+    begin, end = get_markers(file_path)
+
+    start_idx = content.find(begin)
+    if start_idx == -1:
+        # No existing managed region - append at end
+        if content.strip():
+            new_content_wrapped = f"\n{wrap_managed_content(new_content, file_path)}"
+            return content + new_content_wrapped, True
+        return wrap_managed_content(new_content, file_path), True
+
+    end_idx = content.find(end, start_idx)
+    if end_idx == -1:
+        # Malformed - no end marker
+        return content, False
+
+    # Replace region
+    new_content_full = content[:start_idx] + wrap_managed_content(new_content, file_path) + content[end_idx + len(end):]
+    return new_content_full, True
+
+
+def remove_managed_region(content: str, file_path: str) -> tuple[str, bool]:
+    """
+    Remove the managed region from content.
+    
+    Returns:
+        Tuple of (new_content, was_removed)
+    """
+    begin, end = get_markers(file_path)
+
+    start_idx = content.find(begin)
+    if start_idx == -1:
+        return content, False
+
+    end_idx = content.find(end, start_idx)
+    if end_idx == -1:
+        return content, False
+
+    # Remove region including markers
+    new_content = content[:start_idx] + content[end_idx + len(end):]
+    return new_content, True
+
+
+def compute_region_hash(content: str, file_path: str) -> str | None:
+    """Compute hash of managed region content."""
+    import hashlib
+    region = extract_managed_region(content, file_path)
+    if region is None:
+        return None
+    return hashlib.sha256(region.encode("utf-8")).hexdigest()
+
+
+def is_managed_region_modified(content: str, file_path: str, expected_hash: str) -> bool:
+    """Check if managed region has been modified by user."""
+    current_hash = compute_region_hash(content, file_path)
+    if current_hash is None:
+        return True  # No region = modified/corrupted
+    return current_hash != expected_hash

python_skills/skills/__init__.py

@@ -0,0 +1,14 @@
+"""Skills package for python-skills."""
+
+from .loader import SkillLoader
+from .metadata import SkillMetadata, load_skill_metadata
+from .registry import SkillRegistry, get_registry, reset_registry
+
+__all__ = [
+    "SkillRegistry",
+    "get_registry",
+    "reset_registry",
+    "SkillMetadata",
+    "load_skill_metadata",
+    "SkillLoader",
+]

python_skills/skills/loader.py

@@ -0,0 +1,171 @@
+"""Skill loading utilities."""
+
+from pathlib import Path
+
+from .metadata import SkillMetadata, load_skill_metadata
+
+
+class SkillLoader:
+    """Loads skills from the canonical skills directory.
+    
+    Supports two directory layouts:
+    1. Flat files: skills/<category>/<skill-name>.md  (current canonical)
+    2. Agent Skills: skills/<category>/<skill-name>/SKILL.md  (Agent Skills spec)
+    """
+
+    CATEGORIES = frozenset([
+        "core", "stdlib", "generation", "engineering",
+        "quality", "security", "testing", "refactoring",
+        "debugging", "anti_patterns",
+    ])
+
+    def __init__(self, skills_root: Path):
+        self.skills_root = Path(skills_root).resolve()
+
+    def _is_category_dir(self, path: Path) -> bool:
+        """Check if a directory is a valid skill category."""
+        return path.is_dir() and path.name in self.CATEGORIES
+
+    def _discover_skills_in_category(self, category_path: Path) -> list[Path]:
+        """Discover skill paths in a category directory.
+        
+        Returns list of Paths, each pointing to either:
+        - A .md file (flat format)
+        - A directory containing SKILL.md (Agent Skills format)
+        """
+        skills = []
+        if not category_path.is_dir():
+            return skills
+
+        for item in category_path.iterdir():
+            if item.is_file() and item.suffix == ".md" and item.stem != "README":
+                skills.append(item)
+            elif item.is_dir() and (item / "SKILL.md").exists():
+                skills.append(item)
+
+        return skills
+
+    def _discover_root_skills(self) -> list[Path]:
+        """Discover skill .md files at the skills/ root (e.g., core skills)."""
+        skills = []
+        for item in self.skills_root.iterdir():
+            if item.is_file() and item.suffix == ".md" and item.stem != "README":
+                skills.append(item)
+        return skills
+
+    def load_skill(self, skill_name: str) -> SkillMetadata | None:
+        """Load a single skill by name."""
+        # Check root-level flat files first (core skills)
+        root_path = self.skills_root / f"{skill_name}.md"
+        if root_path.is_file():
+            return load_skill_metadata(root_path)
+
+        for category_dir in self.skills_root.iterdir():
+            if not self._is_category_dir(category_dir):
+                continue
+
+            # Check flat file format: <name>.md
+            flat_path = category_dir / f"{skill_name}.md"
+            if flat_path.is_file():
+                return load_skill_metadata(flat_path)
+
+            # Check Agent Skills format: <name>/SKILL.md
+            dir_path = category_dir / skill_name
+            if dir_path.is_dir():
+                return load_skill_metadata(dir_path)
+
+        return None
+
+    def load_category(self, category: str) -> list:
+        """Load all skills in a category."""
+        category_path = self.skills_root / category
+        if not self._is_category_dir(category_path):
+            return []
+
+        skills = []
+        for skill_path in self._discover_skills_in_category(category_path):
+            metadata = load_skill_metadata(skill_path)
+            if metadata:
+                skills.append(metadata)
+        return skills
+
+    def load_all_skills(self) -> list:
+        """Load all skills from all categories and root."""
+        skills = []
+
+        # Load root-level skills (core)
+        for skill_path in self._discover_root_skills():
+            metadata = load_skill_metadata(skill_path)
+            if metadata:
+                skills.append(metadata)
+
+        # Load category skills
+        for category_dir in self.skills_root.iterdir():
+            if self._is_category_dir(category_dir):
+                for skill_path in self._discover_skills_in_category(category_dir):
+                    metadata = load_skill_metadata(skill_path)
+                    if metadata:
+                        skills.append(metadata)
+        return skills
+
+    def get_skill_content(self, skill_name: str) -> str | None:
+        """Get the raw content of a skill."""
+        # Check root-level first
+        root_path = self.skills_root / f"{skill_name}.md"
+        if root_path.is_file():
+            return root_path.read_text(encoding="utf-8")
+
+        for category_dir in self.skills_root.iterdir():
+            if not self._is_category_dir(category_dir):
+                continue
+
+            # Flat format
+            flat_path = category_dir / f"{skill_name}.md"
+            if flat_path.is_file():
+                return flat_path.read_text(encoding="utf-8")
+
+            # Agent Skills format
+            dir_path = category_dir / skill_name / "SKILL.md"
+            if dir_path.exists():
+                return dir_path.read_text(encoding="utf-8")
+
+        return None
+
+    def get_skill_path(self, skill_name: str) -> Path | None:
+        """Get the filesystem path of a skill."""
+        # Check root-level first
+        root_path = self.skills_root / f"{skill_name}.md"
+        if root_path.is_file():
+            return root_path
+
+        for category_dir in self.skills_root.iterdir():
+            if not self._is_category_dir(category_dir):
+                continue
+
+            flat_path = category_dir / f"{skill_name}.md"
+            if flat_path.is_file():
+                return flat_path
+
+            dir_path = category_dir / skill_name / "SKILL.md"
+            if dir_path.exists():
+                return dir_path
+
+        return None
+
+    def get_all_skill_names(self) -> list[str]:
+        """Get list of all skill names."""
+        names = []
+
+        # Root-level skills
+        for skill_path in self._discover_root_skills():
+            names.append(skill_path.stem)
+
+        # Category skills
+        for category_dir in self.skills_root.iterdir():
+            if self._is_category_dir(category_dir):
+                for skill_path in self._discover_skills_in_category(category_dir):
+                    if skill_path.is_file():
+                        names.append(skill_path.stem)
+                    elif skill_path.is_dir():
+                        names.append(skill_path.name)
+        return sorted(names)

python_skills/skills/metadata.py

@@ -0,0 +1,152 @@
+"""Skill metadata handling."""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass
+class SkillMetadata:
+    """Metadata for a skill from its SKILL.md frontmatter or .md file."""
+    name: str
+    category: str
+    path: Path
+    description: str = ""
+    triggers: list[str] = field(default_factory=list)
+    dependencies: list[str] = field(default_factory=list)
+    priority: str = "primary"
+    estimated_tokens: int = 1500
+    raw_frontmatter: dict = field(default_factory=dict)
+    raw_content: str = ""
+
+    @property
+    def skill_name(self) -> str:
+        """Get the skill name (directory or file stem)."""
+        if self.path.is_file():
+            return self.path.stem
+        return self.path.name
+
+
+def parse_skill_frontmatter(content: str) -> tuple[dict, str]:
+    """
+    Parse YAML frontmatter from skill content.
+    
+    Returns:
+        Tuple of (frontmatter_dict, remaining_content)
+    """
+    if not content.startswith("---"):
+        return {}, content
+
+    # Find the closing ---
+    end_idx = content.find("---", 3)
+    if end_idx == -1:
+        return {}, content
+
+    frontmatter_text = content[3:end_idx].strip()
+    remaining = content[end_idx + 3:].lstrip()
+
+    # Simple YAML parsing for our needs
+    frontmatter = {}
+    for line in frontmatter_text.split("\n"):
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if ":" in line:
+            key, value = line.split(":", 1)
+            key = key.strip()
+            value = value.strip().strip('"\'')
+            # Handle lists
+            if value.startswith("[") and value.endswith("]"):
+                value = [v.strip().strip('"\'') for v in value[1:-1].split(",")]
+            frontmatter[key] = value
+
+    return frontmatter, remaining
+
+
+def _extract_description_from_content(content: str) -> str:
+    """Extract a description from markdown content without frontmatter.
+    
+    Looks for patterns like:
+    - **Purpose**: ...
+    - # Title\n\nDescription
+    - First paragraph
+    """
+    lines = content.strip().split("\n")
+
+    for line in lines:
+        line = line.strip()
+        # Look for **Purpose**: pattern
+        if line.lower().startswith("**purpose**:"):
+            return line.split(":", 1)[1].strip()
+        # Look for **When to use**: pattern
+        if line.lower().startswith("**when to use**:"):
+            return line.split(":", 1)[1].strip()
+
+    # Use first heading + next non-empty line
+    found_heading = False
+    for line in lines:
+        line = line.strip()
+        if not line:
+            continue
+        if line.startswith("#"):
+            found_heading = True
+            continue
+        if found_heading and line:
+            return line[:200]
+
+    return ""
+
+
+def load_skill_metadata(skill_path: Path) -> SkillMetadata | None:
+    """Load metadata from a skill path.
+    
+    Supports two formats:
+    1. Flat file: skills/<category>/<name>.md
+    2. Agent Skills: skills/<category>/<name>/SKILL.md
+    """
+    # Determine the actual skill file and content
+    if skill_path.is_file() and skill_path.suffix == ".md":
+        # Flat file format
+        content = skill_path.read_text(encoding="utf-8")
+        skill_name = skill_path.stem
+        skill_file = skill_path
+    elif skill_path.is_dir():
+        # Agent Skills format
+        skill_file = skill_path / "SKILL.md"
+        if not skill_file.exists():
+            return None
+        content = skill_file.read_text(encoding="utf-8")
+        skill_name = skill_path.name
+    else:
+        return None
+
+    frontmatter, content_body = parse_skill_frontmatter(content)
+
+    # Determine category from path
+    # For flat files: parent is the category
+    # For directories: grandparent is the category
+    if skill_path.is_file():
+        category = skill_path.parent.name
+    else:
+        category = skill_path.parent.name
+
+    from .loader import SkillLoader
+    if category not in SkillLoader.CATEGORIES:
+        category = "core"
+
+    # Get description from frontmatter or extract from content
+    description = frontmatter.get("description", "")
+    if not description:
+        description = _extract_description_from_content(content)
+
+    return SkillMetadata(
+        name=skill_name,
+        category=category,
+        path=skill_path,
+        description=description,
+        triggers=frontmatter.get("triggers", []) if isinstance(frontmatter.get("triggers"), list) else [],
+        dependencies=frontmatter.get("dependencies", []) if isinstance(frontmatter.get("dependencies"), list) else [],
+        priority=frontmatter.get("priority", "primary"),
+        estimated_tokens=frontmatter.get("estimated_tokens", 1500) if isinstance(frontmatter.get("estimated_tokens"), int) else 1500,
+        raw_frontmatter=frontmatter,
+        raw_content=content_body,
+    )