agent-skill-manager 0.1.0__py3-none-any.whl → 0.1.2__py3-none-any.whl

skill_manager/deployment.py

@@ -0,0 +1,259 @@
+#!/usr/bin/env python3
+"""
+Skill deployment functionality.
+Handles copying skills to agent directories.
+"""
+
+import shutil
+from collections.abc import Callable
+from pathlib import Path
+
+from .agents import get_agent_path
+from .github import download_skill_from_github
+from .metadata import (
+    list_updatable_skills,
+    read_skill_metadata,
+    update_skill_metadata,
+)
+
+
+def deploy_skill(
+    skill_path: Path,
+    skills_dir: Path,
+    agent_id: str,
+    deployment_type: str = "global",
+    project_root: Path | None = None,
+) -> bool:
+    """
+    Deploy a single skill to an agent's directory.
+
+    Args:
+        skill_path: Relative path to the skill (relative to skills_dir)
+        skills_dir: Base skills directory
+        agent_id: Target agent identifier
+        deployment_type: Either "global" or "project"
+        project_root: Project root directory (required for project deployment)
+
+    Returns:
+        True if deployment succeeded, False otherwise
+    """
+    try:
+        source = skills_dir / skill_path
+        target_base = get_agent_path(agent_id, deployment_type, project_root)
+        target = target_base / skill_path
+
+        # Ensure target directory exists
+        target.parent.mkdir(parents=True, exist_ok=True)
+
+        # Remove existing skill if present
+        if target.exists():
+            shutil.rmtree(target)
+
+        # Copy the skill directory
+        shutil.copytree(source, target)
+        return True
+    except Exception:
+        return False
+
+
+def deploy_skill_to_agents(
+    skill_dir: Path,
+    agents: list[str],
+    deployment_type: str = "global",
+    project_root: Path | None = None,
+) -> tuple[int, int]:
+    """
+    Deploy a skill directory to multiple agents.
+
+    This is used when installing a skill directly from GitHub.
+
+    Args:
+        skill_dir: Path to the skill directory
+        agents: List of agent IDs to deploy to
+        deployment_type: Either "global" or "project"
+        project_root: Project root directory (required for project deployment)
+
+    Returns:
+        Tuple of (success_count, failure_count)
+    """
+    skill_name = skill_dir.name
+    success_count = 0
+    fail_count = 0
+
+    for agent_id in agents:
+        try:
+            target_base = get_agent_path(agent_id, deployment_type, project_root)
+            target_dir = target_base / skill_name
+
+            # Ensure target directory exists
+            target_base.mkdir(parents=True, exist_ok=True)
+
+            # Remove existing skill if present
+            if target_dir.exists():
+                shutil.rmtree(target_dir)
+
+            # Copy the skill directory
+            shutil.copytree(skill_dir, target_dir)
+            success_count += 1
+        except Exception:
+            fail_count += 1
+
+    return success_count, fail_count
+
+
+def deploy_multiple_skills(
+    skill_paths: list[Path],
+    skills_dir: Path,
+    agents: list[str],
+    deployment_type: str = "global",
+    project_root: Path | None = None,
+    progress_callback: Callable | None = None,
+) -> tuple[int, int]:
+    """
+    Deploy multiple skills to multiple agents.
+
+    Args:
+        skill_paths: List of relative skill paths (relative to skills_dir)
+        skills_dir: Base skills directory
+        agents: List of agent IDs to deploy to
+        deployment_type: Either "global" or "project"
+        project_root: Project root directory (required for project deployment)
+        progress_callback: Optional callback for progress updates
+
+    Returns:
+        Tuple of (total_deployed, total_failed)
+    """
+    total_deployed = 0
+    total_failed = 0
+
+    for agent_id in agents:
+        for skill_path in skill_paths:
+            if progress_callback:
+                progress_callback(agent_id, skill_path)
+
+            if deploy_skill(skill_path, skills_dir, agent_id, deployment_type, project_root):
+                total_deployed += 1
+            else:
+                total_failed += 1
+
+    return total_deployed, total_failed
+
+
+def update_skill(
+    skill_name: str,
+    agent_id: str,
+    deployment_type: str = "global",
+    project_root: Path | None = None,
+    progress_callback: Callable | None = None,
+) -> bool:
+    """
+    Update a single skill from its GitHub source.
+
+    Args:
+        skill_name: Name of the skill to update
+        agent_id: Target agent identifier
+        deployment_type: Either "global" or "project"
+        project_root: Project root directory (required for project deployment)
+        progress_callback: Optional callback for progress updates
+
+    Returns:
+        True if update succeeded, False otherwise
+    """
+    try:
+        agent_path = get_agent_path(agent_id, deployment_type, project_root)
+        skill_dir = agent_path / skill_name
+
+        if not skill_dir.exists():
+            return False
+
+        # Read metadata
+        metadata = read_skill_metadata(skill_dir)
+        if not metadata or metadata.get("source") != "github":
+            return False
+
+        # Get GitHub info from metadata
+        github_url = metadata["github_url"]
+
+        if progress_callback:
+            progress_callback(f"Updating {skill_name}...")
+
+        # Download updated version to temporary location
+        temp_dir = agent_path.parent / ".tmp_update"
+        temp_dir.mkdir(exist_ok=True)
+
+        try:
+            updated_skill_dir, _ = download_skill_from_github(github_url, temp_dir)
+
+            # Backup current version
+            backup_dir = agent_path.parent / ".backup"
+            backup_dir.mkdir(exist_ok=True)
+            backup_path = backup_dir / skill_name
+
+            if backup_path.exists():
+                shutil.rmtree(backup_path)
+            shutil.copytree(skill_dir, backup_path)
+
+            # Remove old version
+            shutil.rmtree(skill_dir)
+
+            # Move updated version
+            shutil.move(str(updated_skill_dir), str(skill_dir))
+
+            # Update metadata timestamp
+            update_skill_metadata(skill_dir)
+
+            # Clean up
+            shutil.rmtree(temp_dir, ignore_errors=True)
+            shutil.rmtree(backup_dir, ignore_errors=True)
+
+            return True
+
+        except Exception:
+            # Restore from backup if update failed
+            backup_dir = agent_path.parent / ".backup"
+            backup_path = backup_dir / skill_name
+            if backup_path.exists():
+                if skill_dir.exists():
+                    shutil.rmtree(skill_dir)
+                shutil.copytree(backup_path, skill_dir)
+            shutil.rmtree(temp_dir, ignore_errors=True)
+            shutil.rmtree(backup_dir, ignore_errors=True)
+            return False
+
+    except Exception:
+        return False
+
+
+def update_all_skills(
+    agent_id: str,
+    deployment_type: str = "global",
+    project_root: Path | None = None,
+    progress_callback: Callable | None = None,
+) -> tuple[int, int]:
+    """
+    Update all skills from GitHub for an agent.
+
+    Args:
+        agent_id: Target agent identifier
+        deployment_type: Either "global" or "project"
+        project_root: Project root directory (required for project deployment)
+        progress_callback: Optional callback for progress updates
+
+    Returns:
+        Tuple of (success_count, failure_count)
+    """
+    agent_path = get_agent_path(agent_id, deployment_type, project_root)
+    updatable_skills = list_updatable_skills(agent_path)
+
+    success_count = 0
+    fail_count = 0
+
+    for skill_info in updatable_skills:
+        skill_name = skill_info["skill_name"]
+
+        if update_skill(skill_name, agent_id, deployment_type, project_root, progress_callback):
+            success_count += 1
+        else:
+            fail_count += 1
+
+    return success_count, fail_count

skill_manager/github.py

@@ -0,0 +1,177 @@
+#!/usr/bin/env python3
+"""
+GitHub download functionality for skills.
+Handles URL parsing and downloading files/directories from GitHub.
+"""
+
+from collections.abc import Callable
+from pathlib import Path
+from urllib.parse import urlparse
+
+import httpx
+
+
+def parse_github_url(url: str) -> tuple[str, str, str, str]:
+    """
+    Parse GitHub URL to extract repository information.
+
+    Examples:
+        https://github.com/owner/repo/tree/main/path/to/dir
+        https://github.com/owner/repo/blob/main/path/to/file.py
+
+    Args:
+        url: GitHub URL
+
+    Returns:
+        Tuple of (owner, repo, branch, path)
+
+    Raises:
+        ValueError: If the URL is invalid
+    """
+    parsed = urlparse(url)
+    parts = parsed.path.strip("/").split("/")
+
+    if len(parts) < 2:
+        raise ValueError("Invalid GitHub URL")
+
+    owner = parts[0]
+    repo = parts[1]
+    branch = "main"
+    path = ""
+
+    if len(parts) > 3:
+        # parts[2] is 'tree' or 'blob'
+        # parts[3] is the branch name
+        branch = parts[3]
+        if len(parts) > 4:
+            path = "/".join(parts[4:])
+
+    return owner, repo, branch, path
+
+
+def get_github_content(owner: str, repo: str, path: str, branch: str = "main") -> dict:
+    """
+    Fetch file or directory content using GitHub API.
+
+    Args:
+        owner: Repository owner
+        repo: Repository name
+        path: Path within the repository
+        branch: Branch name (default: "main")
+
+    Returns:
+        JSON response from GitHub API
+
+    Raises:
+        httpx.HTTPStatusError: If the request fails
+    """
+    api_url = f"https://api.github.com/repos/{owner}/{repo}/contents/{path}"
+    params = {"ref": branch}
+
+    with httpx.Client() as client:
+        response = client.get(api_url, params=params, follow_redirects=True)
+        response.raise_for_status()
+        return response.json()
+
+
+def download_file(url: str, dest_path: Path) -> None:
+    """
+    Download a single file from a URL.
+
+    Args:
+        url: File download URL
+        dest_path: Local destination path
+
+    Raises:
+        httpx.HTTPStatusError: If the download fails
+    """
+    with httpx.Client() as client:
+        response = client.get(url, follow_redirects=True)
+        response.raise_for_status()
+        dest_path.parent.mkdir(parents=True, exist_ok=True)
+        dest_path.write_bytes(response.content)
+
+
+def download_directory(
+    owner: str, repo: str, path: str, dest_dir: Path, branch: str = "main"
+) -> None:
+    """
+    Recursively download an entire directory from GitHub.
+
+    Args:
+        owner: Repository owner
+        repo: Repository name
+        path: Path to directory in the repository
+        dest_dir: Local destination directory
+        branch: Branch name (default: "main")
+
+    Raises:
+        httpx.HTTPStatusError: If the download fails
+    """
+    content = get_github_content(owner, repo, path, branch)
+
+    for item in content:
+        item_name = item["name"]
+        item_path = item["path"]
+        item_type = item["type"]
+
+        if item_type == "file":
+            download_url = item["download_url"]
+            file_dest = dest_dir / item_name
+            download_file(download_url, file_dest)
+        elif item_type == "dir":
+            subdir_dest = dest_dir / item_name
+            download_directory(owner, repo, item_path, subdir_dest, branch)
+
+
+def download_skill_from_github(
+    url: str, dest_dir: Path, progress_callback: Callable | None = None
+) -> tuple[Path, dict]:
+    """
+    Download a skill from GitHub to a local directory.
+
+    Args:
+        url: GitHub URL (can be a directory or file)
+        dest_dir: Destination directory
+        progress_callback: Optional callback for progress updates
+
+    Returns:
+        Tuple of (path to downloaded skill directory, metadata dict with owner/repo/branch/path)
+
+    Raises:
+        ValueError: If the URL doesn't point to a directory
+        httpx.HTTPStatusError: If the download fails
+    """
+    # Parse the URL
+    owner, repo, branch, path = parse_github_url(url)
+
+    # Get content information
+    content = get_github_content(owner, repo, path, branch)
+
+    # Must be a directory
+    if not isinstance(content, list):
+        raise ValueError("The provided URL does not point to a directory")
+
+    # Determine skill name from path
+    skill_name = path.split("/")[-1] if path else repo
+    skill_dest = dest_dir / skill_name
+
+    # Create destination directory
+    skill_dest.mkdir(parents=True, exist_ok=True)
+
+    # Download the directory
+    if progress_callback:
+        progress_callback(f"Downloading {skill_name}...")
+
+    download_directory(owner, repo, path, skill_dest, branch)
+
+    # Return path and metadata
+    metadata = {
+        "owner": owner,
+        "repo": repo,
+        "branch": branch,
+        "path": path,
+        "url": url,
+    }
+
+    return skill_dest, metadata

skill_manager/metadata.py

@@ -0,0 +1,140 @@
+#!/usr/bin/env python3
+"""
+Skill metadata management.
+Tracks installation source and update information for skills.
+"""
+
+import json
+from datetime import UTC, datetime
+from pathlib import Path
+
+METADATA_FILENAME = ".skill_metadata.json"
+
+
+def save_skill_metadata(
+    skill_dir: Path,
+    github_url: str,
+    owner: str,
+    repo: str,
+    branch: str,
+    path: str,
+) -> None:
+    """
+    Save metadata for a skill installed from GitHub.
+
+    Args:
+        skill_dir: Path to the skill directory
+        github_url: Original GitHub URL
+        owner: Repository owner
+        repo: Repository name
+        branch: Branch name
+        path: Path within the repository
+    """
+    metadata = {
+        "source": "github",
+        "github_url": github_url,
+        "owner": owner,
+        "repo": repo,
+        "branch": branch,
+        "path": path,
+        "installed_at": datetime.now(UTC).isoformat(),
+        "updated_at": datetime.now(UTC).isoformat(),
+    }
+
+    metadata_file = skill_dir / METADATA_FILENAME
+    metadata_file.write_text(json.dumps(metadata, indent=2))
+
+
+def read_skill_metadata(skill_dir: Path) -> dict | None:
+    """
+    Read metadata for a skill.
+
+    Args:
+        skill_dir: Path to the skill directory
+
+    Returns:
+        Metadata dictionary or None if not found
+    """
+    metadata_file = skill_dir / METADATA_FILENAME
+    if not metadata_file.exists():
+        return None
+
+    try:
+        return json.loads(metadata_file.read_text())
+    except Exception:
+        return None
+
+
+def update_skill_metadata(skill_dir: Path) -> bool:
+    """
+    Update the 'updated_at' timestamp for a skill.
+
+    Args:
+        skill_dir: Path to the skill directory
+
+    Returns:
+        True if updated successfully, False otherwise
+    """
+    metadata = read_skill_metadata(skill_dir)
+    if not metadata:
+        return False
+
+    metadata["updated_at"] = datetime.now(UTC).isoformat()
+
+    metadata_file = skill_dir / METADATA_FILENAME
+    try:
+        metadata_file.write_text(json.dumps(metadata, indent=2))
+        return True
+    except Exception:
+        return False
+
+
+def list_updatable_skills(
+    agent_path: Path,
+) -> list[dict]:
+    """
+    List all skills that have GitHub metadata and can be updated.
+
+    Args:
+        agent_path: Path to the agent's skills directory
+
+    Returns:
+        List of dictionaries containing skill info and metadata
+    """
+    if not agent_path.exists():
+        return []
+
+    updatable_skills = []
+
+    for skill_dir in agent_path.iterdir():
+        if not skill_dir.is_dir() or skill_dir.name.startswith("."):
+            continue
+
+        # Check for SKILL.md
+        if not (skill_dir / "SKILL.md").exists():
+            continue
+
+        # Check for metadata
+        metadata = read_skill_metadata(skill_dir)
+        if metadata and metadata.get("source") == "github":
+            updatable_skills.append({
+                "skill_name": skill_dir.name,
+                "skill_path": skill_dir,
+                "metadata": metadata,
+            })
+
+    return sorted(updatable_skills, key=lambda x: x["skill_name"])
+
+
+def has_github_source(skill_dir: Path) -> bool:
+    """
+    Check if a skill was installed from GitHub.
+
+    Args:
+        skill_dir: Path to the skill directory
+
+    Returns:
+        True if the skill has GitHub metadata, False otherwise
+    """
+    metadata = read_skill_metadata(skill_dir)
+    return metadata is not None and metadata.get("source") == "github"