oasr 0.3.4__py3-none-any.whl

config.py

@@ -0,0 +1,86 @@
+"""Configuration management for ~/.oasr/config.toml."""
+
+import sys
+from pathlib import Path
+from typing import Any
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib
+
+import tomli_w
+
+OASR_DIR = Path.home() / ".oasr"
+CONFIG_FILE = OASR_DIR / "config.toml"
+
+DEFAULT_CONFIG: dict[str, Any] = {
+    "validation": {
+        "reference_max_lines": 500,
+        "strict": False,
+    },
+    "adapter": {
+        "default_targets": ["cursor", "windsurf"],
+    },
+}
+
+
+def ensure_oasr_dir() -> Path:
+    """Ensure ~/.oasr/ directory exists."""
+    OASR_DIR.mkdir(parents=True, exist_ok=True)
+    return OASR_DIR
+
+
+# Legacy alias for backwards compatibility
+def ensure_skills_dir() -> Path:
+    """Legacy alias for ensure_oasr_dir()."""
+    return ensure_oasr_dir()
+
+
+def load_config(config_path: Path | None = None) -> dict[str, Any]:
+    """Load configuration from TOML file.
+
+    Args:
+        config_path: Override config file path. Defaults to ~/.oasr/config.toml.
+
+    Returns:
+        Configuration dictionary with defaults applied.
+    """
+    path = config_path or CONFIG_FILE
+
+    config = DEFAULT_CONFIG.copy()
+    config["validation"] = DEFAULT_CONFIG["validation"].copy()
+    config["adapter"] = DEFAULT_CONFIG["adapter"].copy()
+
+    if path.exists():
+        with open(path, "rb") as f:
+            loaded = tomllib.load(f)
+
+        if "validation" in loaded:
+            config["validation"].update(loaded["validation"])
+        if "adapter" in loaded:
+            config["adapter"].update(loaded["adapter"])
+
+    return config
+
+
+def save_config(config: dict[str, Any], config_path: Path | None = None) -> None:
+    """Save configuration to TOML file.
+
+    Args:
+        config: Configuration dictionary to save.
+        config_path: Override config file path. Defaults to ~/.oasr/config.toml.
+    """
+    path = config_path or CONFIG_FILE
+    ensure_oasr_dir()
+
+    with open(path, "wb") as f:
+        tomli_w.dump(config, f)
+
+
+def get_default_config() -> dict[str, Any]:
+    """Return a copy of the default configuration."""
+    config = DEFAULT_CONFIG.copy()
+    config["validation"] = DEFAULT_CONFIG["validation"].copy()
+    config["adapter"] = DEFAULT_CONFIG["adapter"].copy()
+    return config

discovery.py

@@ -0,0 +1,145 @@
+"""Discovery module for finding SKILL.md files recursively."""
+
+from dataclasses import dataclass
+from pathlib import Path
+
+import yaml
+
+
+@dataclass
+class DiscoveredSkill:
+    """A discovered skill from filesystem."""
+
+    path: Path
+    name: str
+    description: str
+    raw_frontmatter: dict | None = None
+
+
+def parse_frontmatter(content: str) -> dict | None:
+    """Parse YAML frontmatter from markdown content.
+
+    Args:
+        content: Markdown file content.
+
+    Returns:
+        Parsed frontmatter dictionary, or None if not found/invalid.
+    """
+    if not content.startswith("---"):
+        return None
+
+    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
+
+    frontmatter_text = "\n".join(lines[1:end_idx])
+
+    try:
+        return yaml.safe_load(frontmatter_text)
+    except yaml.YAMLError:
+        return None
+
+
+def extract_skill_info(skill_md_path: Path) -> tuple[str, str, dict | None]:
+    """Extract name and description from SKILL.md.
+
+    Args:
+        skill_md_path: Path to SKILL.md file.
+
+    Returns:
+        Tuple of (name, description, raw_frontmatter).
+        Name/description default to empty string if not found.
+    """
+    try:
+        content = skill_md_path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return "", "", None
+
+    frontmatter = parse_frontmatter(content)
+
+    if frontmatter is None:
+        return "", "", None
+
+    name = frontmatter.get("name", "")
+    description = frontmatter.get("description", "")
+
+    if isinstance(name, str):
+        name = name.strip()
+    else:
+        name = ""
+
+    if isinstance(description, str):
+        description = " ".join(description.split())
+    else:
+        description = ""
+
+    return name, description, frontmatter
+
+
+def find_skills(root: Path) -> list[DiscoveredSkill]:
+    """Find all skills recursively under a root directory.
+
+    Args:
+        root: Root directory to search.
+
+    Returns:
+        List of discovered skills.
+    """
+    skills = []
+    root = root.resolve()
+
+    if not root.is_dir():
+        return skills
+
+    for skill_md in root.rglob("SKILL.md"):
+        skill_dir = skill_md.parent
+        name, description, frontmatter = extract_skill_info(skill_md)
+
+        if not name:
+            name = skill_dir.name
+
+        skills.append(
+            DiscoveredSkill(
+                path=skill_dir,
+                name=name,
+                description=description,
+                raw_frontmatter=frontmatter,
+            )
+        )
+
+    return skills
+
+
+def discover_single(path: Path) -> DiscoveredSkill | None:
+    """Discover a single skill at a given path.
+
+    Args:
+        path: Path to skill directory (containing SKILL.md).
+
+    Returns:
+        Discovered skill, or None if not a valid skill.
+    """
+    path = path.resolve()
+    skill_md = path / "SKILL.md"
+
+    if not skill_md.exists():
+        return None
+
+    name, description, frontmatter = extract_skill_info(skill_md)
+
+    if not name:
+        name = path.name
+
+    return DiscoveredSkill(
+        path=path,
+        name=name,
+        description=description,
+        raw_frontmatter=frontmatter,
+    )

manifest.py

@@ -0,0 +1,437 @@
+"""Skill manifest management for auditing and verification.
+
+Manifests track the state of registered skills, enabling:
+- Source verification (content hashing)
+- Change detection (modified files)
+- Existence validation (missing sources)
+- Audit trails (registration timestamps)
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import shutil
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Literal
+
+from remote import check_remote_reachability, fetch_remote_to_temp
+from skillcopy.remote import is_remote_source
+
+MANIFESTS_DIR = "manifests"
+MANIFEST_SUFFIX = ".manifest.json"
+MANIFEST_VERSION = 1
+
+
+@dataclass
+class FileEntry:
+    """A single file in the manifest."""
+
+    path: str
+    hash: str
+    size: int
+
+    def to_dict(self) -> dict:
+        return {"path": self.path, "hash": self.hash, "size": self.size}
+
+    @classmethod
+    def from_dict(cls, data: dict) -> FileEntry:
+        return cls(path=data["path"], hash=data["hash"], size=data["size"])
+
+
+@dataclass
+class SkillManifest:
+    """Manifest for a registered skill."""
+
+    name: str
+    source_path: str
+    description: str
+    registered_at: str
+    content_hash: str
+    files: list[FileEntry] = field(default_factory=list)
+    version: int = MANIFEST_VERSION
+
+    def to_dict(self) -> dict:
+        return {
+            "version": self.version,
+            "name": self.name,
+            "source_path": self.source_path,
+            "description": self.description,
+            "registered_at": self.registered_at,
+            "content_hash": self.content_hash,
+            "files": [f.to_dict() for f in self.files],
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> SkillManifest:
+        return cls(
+            version=data.get("version", 1),
+            name=data["name"],
+            source_path=data["source_path"],
+            description=data["description"],
+            registered_at=data["registered_at"],
+            content_hash=data["content_hash"],
+            files=[FileEntry.from_dict(f) for f in data.get("files", [])],
+        )
+
+
+SkillStatus = Literal["valid", "modified", "missing", "orphaned", "untracked"]
+
+
+@dataclass
+class ManifestStatus:
+    """Status of a skill manifest check."""
+
+    name: str
+    status: SkillStatus
+    source_path: str | None = None
+    message: str = ""
+    changed_files: list[str] = field(default_factory=list)
+    added_files: list[str] = field(default_factory=list)
+    removed_files: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return {
+            "name": self.name,
+            "status": self.status,
+            "source_path": self.source_path,
+            "message": self.message,
+            "changed_files": self.changed_files,
+            "added_files": self.added_files,
+            "removed_files": self.removed_files,
+        }
+
+
+def hash_file(path: Path) -> str:
+    """Compute SHA256 hash of a file.
+
+    Args:
+        path: Path to the file.
+
+    Returns:
+        Hash string in format "sha256:<hex>".
+    """
+    hasher = hashlib.sha256()
+    try:
+        with open(path, "rb") as f:
+            for chunk in iter(lambda: f.read(8192), b""):
+                hasher.update(chunk)
+        return f"sha256:{hasher.hexdigest()}"
+    except OSError:
+        return "sha256:error"
+
+
+def hash_directory(path: Path) -> tuple[str, list[FileEntry]]:
+    """Compute content hash of a directory.
+
+    Creates a deterministic hash based on all file paths and their contents.
+
+    Args:
+        path: Path to the directory.
+
+    Returns:
+        Tuple of (content_hash, list of FileEntry).
+    """
+    entries = []
+    hasher = hashlib.sha256()
+
+    if not path.is_dir():
+        return "sha256:missing", []
+
+    files = sorted(path.rglob("*"))
+
+    for file_path in files:
+        if file_path.is_file():
+            rel_path = str(file_path.relative_to(path))
+            file_hash = hash_file(file_path)
+            file_size = file_path.stat().st_size
+
+            entries.append(
+                FileEntry(
+                    path=rel_path,
+                    hash=file_hash,
+                    size=file_size,
+                )
+            )
+
+            hasher.update(rel_path.encode("utf-8"))
+            hasher.update(file_hash.encode("utf-8"))
+
+    return f"sha256:{hasher.hexdigest()}", entries
+
+
+def get_manifests_dir(config_dir: Path | None = None) -> Path:
+    """Get the manifests directory path.
+
+    Args:
+        config_dir: Override config directory (default: ~/.oasr).
+
+    Returns:
+        Path to manifests directory.
+    """
+    if config_dir is None:
+        config_dir = Path.home() / ".oasr"
+    return config_dir / MANIFESTS_DIR
+
+
+def create_manifest(
+    name: str,
+    source_path: Path | str,
+    description: str,
+) -> SkillManifest:
+    """Create a new manifest for a skill.
+
+    Args:
+        name: Skill name.
+        source_path: Absolute path to skill directory or remote URL.
+        description: Skill description.
+
+    Returns:
+        New SkillManifest instance.
+    """
+    source_path_str = str(source_path)
+
+    # Handle remote sources
+    if is_remote_source(source_path_str):
+        temp_dir = fetch_remote_to_temp(source_path_str)
+        try:
+            content_hash, files = hash_directory(temp_dir)
+        finally:
+            shutil.rmtree(temp_dir, ignore_errors=True)
+    else:
+        # Handle local sources
+        content_hash, files = hash_directory(Path(source_path_str))
+
+    return SkillManifest(
+        name=name,
+        source_path=source_path_str,
+        description=description,
+        registered_at=datetime.now(timezone.utc).isoformat(),
+        content_hash=content_hash,
+        files=files,
+    )
+
+
+def save_manifest(manifest: SkillManifest, config_dir: Path | None = None) -> Path:
+    """Save a manifest to disk.
+
+    Args:
+        manifest: Manifest to save.
+        config_dir: Override config directory.
+
+    Returns:
+        Path to saved manifest file.
+    """
+    manifests_dir = get_manifests_dir(config_dir)
+    manifests_dir.mkdir(parents=True, exist_ok=True)
+
+    manifest_path = manifests_dir / f"{manifest.name}{MANIFEST_SUFFIX}"
+    manifest_path.write_text(
+        json.dumps(manifest.to_dict(), indent=2),
+        encoding="utf-8",
+    )
+
+    return manifest_path
+
+
+def load_manifest(name: str, config_dir: Path | None = None) -> SkillManifest | None:
+    """Load a manifest from disk.
+
+    Args:
+        name: Skill name.
+        config_dir: Override config directory.
+
+    Returns:
+        SkillManifest if found, None otherwise.
+    """
+    manifests_dir = get_manifests_dir(config_dir)
+    manifest_path = manifests_dir / f"{name}{MANIFEST_SUFFIX}"
+
+    if not manifest_path.is_file():
+        return None
+
+    try:
+        data = json.loads(manifest_path.read_text(encoding="utf-8"))
+        return SkillManifest.from_dict(data)
+    except (json.JSONDecodeError, KeyError, OSError):
+        return None
+
+
+def delete_manifest(name: str, config_dir: Path | None = None) -> bool:
+    """Delete a manifest from disk.
+
+    Args:
+        name: Skill name.
+        config_dir: Override config directory.
+
+    Returns:
+        True if deleted, False if not found.
+    """
+    manifests_dir = get_manifests_dir(config_dir)
+    manifest_path = manifests_dir / f"{name}{MANIFEST_SUFFIX}"
+
+    if manifest_path.is_file():
+        manifest_path.unlink()
+        return True
+    return False
+
+
+def list_manifests(config_dir: Path | None = None) -> list[str]:
+    """List all manifest names.
+
+    Args:
+        config_dir: Override config directory.
+
+    Returns:
+        List of skill names with manifests.
+    """
+    manifests_dir = get_manifests_dir(config_dir)
+
+    if not manifests_dir.is_dir():
+        return []
+
+    names = []
+    for path in manifests_dir.glob(f"*{MANIFEST_SUFFIX}"):
+        name = path.name[: -len(MANIFEST_SUFFIX)]
+        names.append(name)
+
+    return sorted(names)
+
+
+def check_manifest(manifest: SkillManifest) -> ManifestStatus:
+    """Check if a manifest matches its source.
+
+    Args:
+        manifest: Manifest to check.
+
+    Returns:
+        ManifestStatus with validation results.
+    """
+    source_path_str = manifest.source_path
+
+    # Handle remote sources
+    if is_remote_source(source_path_str):
+        # Check remote reachability
+        reachable, status_code, message = check_remote_reachability(source_path_str)
+
+        if not reachable:
+            if status_code in (404, 410):
+                return ManifestStatus(
+                    name=manifest.name,
+                    status="missing",
+                    source_path=source_path_str,
+                    message=f"Remote source not found: {message}",
+                )
+            else:
+                # Network error - assume valid (transient)
+                return ManifestStatus(
+                    name=manifest.name,
+                    status="valid",
+                    source_path=source_path_str,
+                    message=f"Cannot verify remote (network issue): {message}",
+                )
+
+        # Fetch current content to temp dir
+        try:
+            temp_dir = fetch_remote_to_temp(source_path_str)
+        except Exception as e:
+            return ManifestStatus(
+                name=manifest.name,
+                status="valid",
+                source_path=source_path_str,
+                message=f"Cannot fetch remote (assuming unchanged): {e}",
+            )
+
+        try:
+            current_hash, current_files = hash_directory(temp_dir)
+        finally:
+            shutil.rmtree(temp_dir, ignore_errors=True)
+    else:
+        # Handle local sources
+        source_path = Path(source_path_str)
+
+        if not source_path.exists():
+            return ManifestStatus(
+                name=manifest.name,
+                status="missing",
+                source_path=source_path_str,
+                message=f"Source path no longer exists: {source_path_str}",
+            )
+
+        current_hash, current_files = hash_directory(source_path)
+
+    # Compare hashes
+    if current_hash == manifest.content_hash:
+        return ManifestStatus(
+            name=manifest.name,
+            status="valid",
+            source_path=source_path_str,
+            message="Source matches manifest",
+        )
+
+    # Compute differences
+    current_file_map = {f.path: f for f in current_files}
+    manifest_file_map = {f.path: f for f in manifest.files}
+
+    changed = []
+    added = []
+    removed = []
+
+    for path, entry in current_file_map.items():
+        if path not in manifest_file_map:
+            added.append(path)
+        elif entry.hash != manifest_file_map[path].hash:
+            changed.append(path)
+
+    for path in manifest_file_map:
+        if path not in current_file_map:
+            removed.append(path)
+
+    return ManifestStatus(
+        name=manifest.name,
+        status="modified",
+        source_path=source_path_str,
+        message=f"Source modified: {len(changed)} changed, {len(added)} added, {len(removed)} removed",
+        changed_files=changed,
+        added_files=added,
+        removed_files=removed,
+    )
+
+
+def sync_manifest(manifest: SkillManifest, config_dir: Path | None = None) -> SkillManifest:
+    """Update a manifest to match current source state.
+
+    Args:
+        manifest: Existing manifest.
+        config_dir: Override config directory.
+
+    Returns:
+        Updated manifest (also saved to disk).
+    """
+    source_path_str = manifest.source_path
+
+    # Handle remote sources
+    if is_remote_source(source_path_str):
+        temp_dir = fetch_remote_to_temp(source_path_str)
+        try:
+            content_hash, files = hash_directory(temp_dir)
+        finally:
+            shutil.rmtree(temp_dir, ignore_errors=True)
+    else:
+        # Handle local sources
+        source_path = Path(source_path_str)
+        content_hash, files = hash_directory(source_path)
+
+    updated = SkillManifest(
+        name=manifest.name,
+        source_path=manifest.source_path,
+        description=manifest.description,
+        registered_at=manifest.registered_at,
+        content_hash=content_hash,
+        files=files,
+    )
+
+    save_manifest(updated, config_dir)
+    return updated