oasr 0.3.4__py3-none-any.whl

skillcopy/__init__.py

@@ -0,0 +1,71 @@
+"""Unified interface for copying skills (local or remote).
+
+This module provides a single entry point for copying skills from any source
+(local filesystem or remote URL) to a destination directory.
+"""
+
+from pathlib import Path
+
+from .local import copy_local_skill
+from .remote import copy_remote_skill, is_remote_source
+
+
+def copy_skill(
+    source: str,
+    dest: Path,
+    *,
+    validate: bool = True,
+    show_progress: bool = False,
+    skill_name: str = None,
+    inject_tracking: bool = False,
+    source_hash: str | None = None,
+) -> Path:
+    """Copy a skill from source (path or URL) to destination.
+
+    Args:
+        source: Local path or remote URL
+        dest: Destination directory
+        validate: Whether to validate skill structure after copy
+        show_progress: If True, show progress messages for remote skills
+        skill_name: Optional skill name for progress messages
+        inject_tracking: If True, inject metadata.oasr tracking info
+        source_hash: Optional content hash for tracking (required if inject_tracking=True)
+
+    Returns:
+        Path to copied skill directory
+
+    Raises:
+        ValueError: If source is invalid or inject_tracking=True without source_hash
+        OSError: If copy operation fails
+    """
+    if inject_tracking and source_hash is None:
+        raise ValueError("source_hash required when inject_tracking=True")
+
+    if is_remote_source(source):
+        dest_path = copy_remote_skill(
+            source, dest, validate=validate, show_progress=show_progress, skill_name=skill_name
+        )
+    else:
+        dest_path = copy_local_skill(source, dest, validate=validate)
+
+    # Inject tracking metadata if requested
+    if inject_tracking:
+        try:
+            from tracking import inject_metadata
+
+            success = inject_metadata(dest_path, source_hash, source)
+            if not success:
+                # Log warning but don't fail the copy
+                import sys
+
+                print(f"Warning: Failed to inject tracking metadata for {dest_path.name}", file=sys.stderr)
+        except Exception as e:
+            # Log warning but don't fail the copy
+            import sys
+
+            print(f"Warning: Error injecting tracking metadata: {e}", file=sys.stderr)
+
+    return dest_path
+
+
+__all__ = ["copy_skill", "is_remote_source"]

skillcopy/local.py

@@ -0,0 +1,40 @@
+"""Local filesystem skill copy operations."""
+
+import shutil
+from pathlib import Path
+
+
+def copy_local_skill(source: str, dest: Path, *, validate: bool = True) -> Path:
+    """Copy a skill from local filesystem to destination.
+
+    Args:
+        source: Local filesystem path
+        dest: Destination directory
+        validate: Whether to validate skill structure (reserved for future)
+
+    Returns:
+        Path to copied skill directory
+
+    Raises:
+        FileNotFoundError: If source doesn't exist
+        OSError: If copy operation fails
+    """
+    src_path = Path(source).resolve()
+
+    if not src_path.exists():
+        raise FileNotFoundError(f"Source path does not exist: {source}")
+
+    if not src_path.is_dir():
+        raise ValueError(f"Source is not a directory: {source}")
+
+    dest = dest.resolve()
+
+    # Remove existing destination if it exists
+    if dest.exists():
+        shutil.rmtree(dest)
+
+    # Copy skill directory
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copytree(src_path, dest)
+
+    return dest

skillcopy/remote.py

@@ -0,0 +1,98 @@
+"""Remote skill fetch and copy operations."""
+
+import shutil
+import sys
+from pathlib import Path
+
+from remote import fetch_remote_to_temp
+
+
+def is_remote_source(source: str) -> bool:
+    """Check if source is a remote URL.
+
+    Args:
+        source: Path or URL string
+
+    Returns:
+        True if source is a URL, False otherwise
+    """
+    return isinstance(source, str) and (source.startswith("http://") or source.startswith("https://"))
+
+
+def copy_remote_skill(
+    url: str,
+    dest: Path,
+    *,
+    validate: bool = True,
+    force_refresh: bool = False,
+    show_progress: bool = False,
+    skill_name: str = None,
+) -> Path:
+    """Copy a skill from remote URL to destination.
+
+    Smart caching: If destination exists and content matches manifest hash,
+    skip the fetch to avoid unnecessary API calls.
+
+    Args:
+        url: Remote skill URL
+        dest: Destination directory
+        validate: Whether to validate skill structure (reserved for future)
+        force_refresh: If True, always fetch (ignore cache)
+        show_progress: If True, print progress messages
+        skill_name: Optional skill name for progress messages
+
+    Returns:
+        Path to copied skill directory
+
+    Raises:
+        ValueError: If URL is invalid
+        OSError: If fetch or copy operation fails
+    """
+    dest = dest.resolve()
+
+    # Smart check: if destination exists and is up-to-date, skip fetch
+    if not force_refresh and dest.exists():
+        try:
+            from manifest import hash_directory, load_manifest
+
+            # Try to load manifest to get expected hash
+            # Derive skill name from destination directory name
+            check_name = skill_name or dest.name
+            manifest = load_manifest(check_name)
+
+            # If manifest source matches this URL, compare hashes
+            if manifest and manifest.source_path == url:
+                current_hash, _ = hash_directory(dest)
+                if current_hash == manifest.content_hash:
+                    # Destination is up-to-date, no need to fetch
+                    if show_progress:
+                        print(f"  ✓ {skill_name or dest.name} (cached)", file=sys.stderr)
+                    return dest
+        except Exception:
+            # If any error checking cache, proceed with fetch
+            pass
+
+    # Show progress before fetching
+    if show_progress:
+        platform = "GitHub" if "github.com" in url else "GitLab" if "gitlab.com" in url else "remote"
+        print(f"  ↓ {skill_name or dest.name} (fetching from {platform}...)", file=sys.stderr, flush=True)
+
+    # Fetch to temporary directory
+    temp_dir = fetch_remote_to_temp(url)
+
+    try:
+        # Remove existing destination if it exists
+        if dest.exists():
+            shutil.rmtree(dest)
+
+        # Copy from temp to destination
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copytree(temp_dir, dest)
+
+        if show_progress:
+            print(f"  ✓ {skill_name or dest.name} (downloaded)", file=sys.stderr)
+
+        return dest
+    finally:
+        # Clean up temporary directory
+        shutil.rmtree(temp_dir, ignore_errors=True)

tracking.py

@@ -0,0 +1,181 @@
+"""Skill tracking via metadata.oasr frontmatter injection.
+
+This module handles injecting and extracting tracking metadata in SKILL.md files.
+Tracking metadata is stored under the `metadata.oasr` field to comply with the
+Open Agent Skill specification.
+"""
+
+from datetime import datetime, timezone
+from pathlib import Path
+
+import yaml
+
+
+def inject_metadata(skill_path: Path, content_hash: str, source: str) -> bool:
+    """Inject tracking metadata into SKILL.md frontmatter.
+
+    Args:
+        skill_path: Path to skill directory
+        content_hash: SHA256 hash of the skill content
+        source: Source path or URL of the skill
+
+    Returns:
+        True if metadata was injected, False if SKILL.md not found or injection failed
+
+    Raises:
+        OSError: If file cannot be read or written (permission, encoding issues)
+    """
+    skill_md = skill_path / "SKILL.md"
+    if not skill_md.exists():
+        return False
+
+    try:
+        content = skill_md.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError) as e:
+        raise OSError(f"Failed to read {skill_md}: {e}") from e
+
+    # Parse existing frontmatter
+    frontmatter, body = _split_frontmatter(content)
+
+    if frontmatter is None:
+        # No frontmatter exists - shouldn't happen for valid skills, but handle it
+        return False
+
+    # Validate frontmatter is a dict
+    if not isinstance(frontmatter, dict):
+        return False
+
+    # Ensure metadata field exists
+    if "metadata" not in frontmatter:
+        frontmatter["metadata"] = {}
+    elif not isinstance(frontmatter["metadata"], dict):
+        # metadata exists but is not a dict - fix it
+        frontmatter["metadata"] = {}
+
+    # Inject oasr tracking metadata
+    frontmatter["metadata"]["oasr"] = {
+        "hash": content_hash,
+        "source": str(source),
+        "synced": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
+    }
+
+    # Write back
+    try:
+        new_content = _serialize_frontmatter(frontmatter) + body
+        skill_md.write_text(new_content, encoding="utf-8")
+    except (OSError, UnicodeEncodeError) as e:
+        raise OSError(f"Failed to write {skill_md}: {e}") from e
+
+    return True
+
+
+def extract_metadata(skill_path: Path) -> dict | None:
+    """Extract tracking metadata from SKILL.md.
+
+    Args:
+        skill_path: Path to skill directory
+
+    Returns:
+        Dictionary with 'hash', 'source', 'synced' keys, or None if not tracked
+        Returns None on any error (file not found, encoding issues, corrupted metadata)
+    """
+    skill_md = skill_path / "SKILL.md"
+    if not skill_md.exists():
+        return None
+
+    try:
+        content = skill_md.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        # Cannot read file - treat as untracked
+        return None
+
+    frontmatter, _ = _split_frontmatter(content)
+
+    if frontmatter is None or not isinstance(frontmatter, dict):
+        return None
+
+    # Safely extract metadata.oasr
+    metadata = frontmatter.get("metadata")
+    if not isinstance(metadata, dict):
+        return None
+
+    oasr = metadata.get("oasr")
+    if not isinstance(oasr, dict):
+        return None
+
+    # Validate required fields
+    if "hash" not in oasr or "source" not in oasr:
+        return None
+
+    return oasr
+
+
+def strip_tracking_metadata(frontmatter: dict) -> dict:
+    """Remove metadata.oasr from frontmatter dictionary.
+
+    This is used when comparing registry skills to avoid flagging
+    tracking metadata as drift.
+
+    Args:
+        frontmatter: Frontmatter dictionary
+
+    Returns:
+        Copy of frontmatter with metadata.oasr removed
+    """
+    import copy
+
+    cleaned = copy.deepcopy(frontmatter)
+
+    if "metadata" in cleaned and isinstance(cleaned["metadata"], dict):
+        cleaned["metadata"].pop("oasr", None)
+        # Remove metadata field entirely if it's now empty
+        if not cleaned["metadata"]:
+            cleaned.pop("metadata")
+
+    return cleaned
+
+
+def _split_frontmatter(content: str) -> tuple[dict | None, str]:
+    """Split markdown content into frontmatter and body.
+
+    Args:
+        content: Full markdown content
+
+    Returns:
+        Tuple of (frontmatter_dict, body_text)
+    """
+    if not content.startswith("---"):
+        return None, content
+
+    lines = content.split("\n")
+    end_idx = None
+
+    for i, line in enumerate(lines[1:], start=1):
+        if line.strip() == "---":
+            end_idx = i
+            break
+
+    if end_idx is None:
+        return None, content
+
+    frontmatter_text = "\n".join(lines[1:end_idx])
+    body_text = "\n".join(lines[end_idx + 1 :])
+
+    try:
+        frontmatter = yaml.safe_load(frontmatter_text)
+        return frontmatter, body_text
+    except yaml.YAMLError:
+        return None, content
+
+
+def _serialize_frontmatter(frontmatter: dict) -> str:
+    """Serialize frontmatter dictionary back to YAML with delimiters.
+
+    Args:
+        frontmatter: Frontmatter dictionary
+
+    Returns:
+        YAML string with --- delimiters
+    """
+    yaml_str = yaml.safe_dump(frontmatter, default_flow_style=False, allow_unicode=True, sort_keys=False)
+    return f"---\n{yaml_str}---\n"