oasr 0.5.0__py3-none-any.whl

__init__.py

@@ -0,0 +1,3 @@
+"""ASR CLI - Manage agent skills across IDE integrations."""
+
+__version__ = "0.3.4"

__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for python -m (installed module layout)."""
+
+from cli import main
+
+if __name__ == "__main__":
+    main()

adapter.py

@@ -0,0 +1,396 @@
+"""Pure Python adapter generation - self-contained and portable.
+
+This module provides standalone adapter generation for Cursor, Windsurf, and Codex
+without dependencies on other CLI modules. Can be used as a library or run directly.
+
+Usage:
+    python -m skills.adapter --skills-root /path/to/skills --output-dir /path/to/project
+    python -m skills.adapter --skills-root /path/to/skills --target cursor
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+
+try:
+    import yaml
+
+    HAS_YAML = True
+except ImportError:
+    HAS_YAML = False
+
+
+@dataclass
+class SkillInfo:
+    """Discovered skill information."""
+
+    name: str
+    description: str
+    path: Path
+
+
+def parse_frontmatter(content: str) -> dict[str, str]:
+    """Parse YAML frontmatter from markdown content.
+
+    Args:
+        content: Markdown file content.
+
+    Returns:
+        Dictionary of frontmatter fields, empty if no valid frontmatter.
+    """
+    if not content.startswith("---"):
+        return {}
+
+    lines = content.split("\n")
+    end_idx = -1
+
+    for i, line in enumerate(lines[1:], start=1):
+        if line.strip() == "---":
+            end_idx = i
+            break
+
+    if end_idx == -1:
+        return {}
+
+    fm_text = "\n".join(lines[1:end_idx])
+
+    if HAS_YAML:
+        try:
+            parsed = yaml.safe_load(fm_text)
+            if isinstance(parsed, dict):
+                return {k: str(v) if v else "" for k, v in parsed.items()}
+        except yaml.YAMLError:
+            pass
+
+    frontmatter = {}
+    for line in lines[1:end_idx]:
+        if ":" in line and not line.startswith(" ") and not line.startswith("\t"):
+            key, _, value = line.partition(":")
+            frontmatter[key.strip()] = value.strip().strip('"').strip("'")
+
+    return frontmatter
+
+
+def find_skills(root: Path) -> list[SkillInfo]:
+    """Recursively find all SKILL.md files and extract skill info.
+
+    Args:
+        root: Root directory to search.
+
+    Returns:
+        List of discovered skills with name, description, and path.
+    """
+    skills = []
+
+    for skill_md in root.rglob("SKILL.md"):
+        skill_dir = skill_md.parent
+
+        try:
+            content = skill_md.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError):
+            continue
+
+        fm = parse_frontmatter(content)
+        name = fm.get("name", skill_dir.name)
+        description = fm.get("description", "")
+
+        if not name:
+            continue
+
+        skills.append(
+            SkillInfo(
+                name=name,
+                description=description,
+                path=skill_dir.resolve(),
+            )
+        )
+
+    return skills
+
+
+def generate_cursor(skill: SkillInfo, output_dir: Path) -> Path:
+    """Generate a Cursor command file.
+
+    Args:
+        skill: Skill information.
+        output_dir: Target directory (will create .cursor/commands/).
+
+    Returns:
+        Path to the generated file.
+    """
+    target_dir = output_dir / ".cursor" / "commands"
+    target_dir.mkdir(parents=True, exist_ok=True)
+
+    output_file = target_dir / f"{skill.name}.md"
+
+    content = f"""# {skill.name}
+
+{skill.description}
+
+This command delegates to the agent skill at `{skill.path}/`.
+
+## Skill Location
+
+- **Path:** `{skill.path}/`
+- **Manifest:** `{skill.path}/SKILL.md`
+"""
+
+    output_file.write_text(content, encoding="utf-8")
+    return output_file
+
+
+def generate_windsurf(skill: SkillInfo, output_dir: Path) -> Path:
+    """Generate a Windsurf workflow file.
+
+    Args:
+        skill: Skill information.
+        output_dir: Target directory (will create .windsurf/workflows/).
+
+    Returns:
+        Path to the generated file.
+    """
+    target_dir = output_dir / ".windsurf" / "workflows"
+    target_dir.mkdir(parents=True, exist_ok=True)
+
+    output_file = target_dir / f"{skill.name}.md"
+
+    desc_yaml = json.dumps(skill.description)
+
+    content = f"""---
+description: {desc_yaml}
+auto_execution_mode: 1
+---
+
+# {skill.name}
+
+This workflow delegates to the agent skill at `{skill.path}/`.
+
+## Skill Location
+
+- **Path:** `{skill.path}/`
+- **Manifest:** `{skill.path}/SKILL.md`
+"""
+
+    output_file.write_text(content, encoding="utf-8")
+    return output_file
+
+
+def generate_codex(skill: SkillInfo, output_dir: Path) -> Path:
+    """Generate a Codex skill file (placeholder, uses Cursor format).
+
+    Args:
+        skill: Skill information.
+        output_dir: Target directory (will create .codex/skills/).
+
+    Returns:
+        Path to the generated file.
+    """
+    target_dir = output_dir / ".codex" / "skills"
+    target_dir.mkdir(parents=True, exist_ok=True)
+
+    output_file = target_dir / f"{skill.name}.md"
+
+    content = f"""# {skill.name}
+
+{skill.description}
+
+This skill delegates to the agent skill at `{skill.path}/`.
+
+## Skill Location
+
+- **Path:** `{skill.path}/`
+- **Manifest:** `{skill.path}/SKILL.md`
+"""
+
+    output_file.write_text(content, encoding="utf-8")
+    return output_file
+
+
+def cleanup_stale(
+    output_dir: Path,
+    subdir: str,
+    valid_names: set[str],
+    marker: str,
+) -> list[Path]:
+    """Remove stale generated files.
+
+    Args:
+        output_dir: Base output directory.
+        subdir: Subdirectory path (e.g., ".cursor/commands").
+        valid_names: Set of valid skill names to keep.
+        marker: Text marker to identify generated files.
+
+    Returns:
+        List of removed file paths.
+    """
+    removed = []
+    target_dir = output_dir / subdir
+
+    if not target_dir.is_dir():
+        return removed
+
+    for file in target_dir.glob("*.md"):
+        name = file.stem
+
+        if name in valid_names:
+            continue
+
+        try:
+            content = file.read_text(encoding="utf-8")
+            if marker in content:
+                file.unlink()
+                removed.append(file)
+        except (OSError, UnicodeDecodeError):
+            pass
+
+    return removed
+
+
+ADAPTERS: dict[str, tuple[Callable[[SkillInfo, Path], Path], str, str]] = {
+    "cursor": (generate_cursor, ".cursor/commands", "This command delegates to the agent skill at"),
+    "windsurf": (generate_windsurf, ".windsurf/workflows", "This workflow delegates to the agent skill at"),
+    "codex": (generate_codex, ".codex/skills", "This skill delegates to the agent skill at"),
+}
+
+
+def generate_adapters(
+    skills_root: Path,
+    output_dir: Path,
+    targets: list[str] | None = None,
+    exclude: set[str] | None = None,
+    cleanup: bool = True,
+) -> dict[str, dict]:
+    """Generate adapter files for all skills.
+
+    Args:
+        skills_root: Root directory containing skills.
+        output_dir: Output directory for generated files.
+        targets: List of adapter targets (default: all).
+        exclude: Set of skill names to exclude.
+        cleanup: Whether to remove stale files.
+
+    Returns:
+        Dictionary with results per target.
+    """
+    if targets is None:
+        targets = list(ADAPTERS.keys())
+
+    if exclude is None:
+        exclude = set()
+
+    skills = find_skills(skills_root)
+    skills = [s for s in skills if s.name not in exclude]
+    valid_names = {s.name for s in skills}
+
+    results = {}
+
+    for target in targets:
+        if target not in ADAPTERS:
+            continue
+
+        generator, subdir, marker = ADAPTERS[target]
+        generated = []
+        removed = []
+
+        for skill in skills:
+            path = generator(skill, output_dir)
+            generated.append(path)
+
+        if cleanup:
+            removed = cleanup_stale(output_dir, subdir, valid_names, marker)
+
+        results[target] = {
+            "generated": [str(p) for p in generated],
+            "removed": [str(p) for p in removed],
+            "output_dir": str(output_dir / subdir),
+        }
+
+    return results
+
+
+def main(argv: list[str] | None = None) -> int:
+    """CLI entry point for standalone adapter generation."""
+    parser = argparse.ArgumentParser(
+        prog="skills.adapter",
+        description="Generate IDE adapter files from SKILL.md files.",
+    )
+    parser.add_argument(
+        "--skills-root",
+        type=Path,
+        required=True,
+        help="Root directory containing skills",
+    )
+    parser.add_argument(
+        "--output-dir",
+        type=Path,
+        default=Path("."),
+        help="Output directory (default: current)",
+    )
+    parser.add_argument(
+        "--target",
+        choices=list(ADAPTERS.keys()),
+        action="append",
+        dest="targets",
+        help="Target adapter(s) to generate (default: all)",
+    )
+    parser.add_argument(
+        "--exclude",
+        help="Comma-separated skill names to exclude",
+    )
+    parser.add_argument(
+        "--no-cleanup",
+        action="store_true",
+        help="Don't remove stale files",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output results as JSON",
+    )
+    parser.add_argument(
+        "--quiet",
+        action="store_true",
+        help="Suppress output",
+    )
+
+    args = parser.parse_args(argv)
+
+    skills_root = args.skills_root.resolve()
+    output_dir = args.output_dir.resolve()
+
+    if not skills_root.is_dir():
+        print(f"Error: Not a directory: {skills_root}", file=sys.stderr)
+        return 2
+
+    exclude = set()
+    if args.exclude:
+        exclude = set(args.exclude.split(","))
+
+    results = generate_adapters(
+        skills_root=skills_root,
+        output_dir=output_dir,
+        targets=args.targets,
+        exclude=exclude,
+        cleanup=not args.no_cleanup,
+    )
+
+    if args.json:
+        print(json.dumps(results, indent=2))
+    elif not args.quiet:
+        for target, info in results.items():
+            gen_count = len(info["generated"])
+            rem_count = len(info["removed"])
+            print(f"{target}: Generated {gen_count} file(s) in {info['output_dir']}")
+            if rem_count:
+                print(f"  Removed {rem_count} stale file(s)")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

adapters/__init__.py

@@ -0,0 +1,17 @@
+"""Adapter modules for generating IDE-specific skill files."""
+
+from adapters.base import BaseAdapter
+from adapters.claude import ClaudeAdapter
+from adapters.codex import CodexAdapter
+from adapters.copilot import CopilotAdapter
+from adapters.cursor import CursorAdapter
+from adapters.windsurf import WindsurfAdapter
+
+__all__ = [
+    "BaseAdapter",
+    "CursorAdapter",
+    "WindsurfAdapter",
+    "CodexAdapter",
+    "CopilotAdapter",
+    "ClaudeAdapter",
+]

adapters/base.py

@@ -0,0 +1,254 @@
+"""Base adapter interface for generating IDE-specific skill files."""
+
+import sys
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Protocol
+
+from skillcopy import copy_skill as copy_skill_unified
+
+
+class SkillInfo(Protocol):
+    """Protocol for skill information."""
+
+    path: str
+    name: str
+    description: str
+
+
+class BaseAdapter(ABC):
+    """Abstract base class for adapters."""
+
+    target_name: str = ""
+    target_subdir: str = ""
+
+    def resolve_output_dir(self, output_dir: Path) -> Path:
+        """Resolve the actual output directory based on smart path detection.
+
+        If output_dir ends with the target subdir pattern, use it directly.
+        Otherwise, append the target subdir.
+
+        Args:
+            output_dir: User-specified output directory.
+
+        Returns:
+            Resolved output directory path.
+        """
+        output_str = str(output_dir)
+
+        if output_str.endswith(self.target_subdir):
+            return output_dir
+
+        base_dir = self.target_subdir.rsplit("/", 1)[0]
+        if output_str.endswith(base_dir):
+            subdir_name = self.target_subdir.rsplit("/", 1)[1]
+            return output_dir / subdir_name
+
+        return output_dir / self.target_subdir
+
+    @abstractmethod
+    def generate(
+        self, skill: SkillInfo, output_dir: Path, copy: bool = True, base_output_dir: Path | None = None
+    ) -> Path:
+        """Generate IDE-specific file for a skill.
+
+        Args:
+            skill: Skill information.
+            output_dir: Resolved output directory for adapter files.
+            copy: Always True (kept for backward compatibility).
+            base_output_dir: Base output directory (for computing relative paths).
+
+        Returns:
+            Path to the generated file.
+        """
+        pass
+
+    @abstractmethod
+    def cleanup_stale(self, output_dir: Path, valid_names: set[str]) -> list[Path]:
+        """Remove stale generated files.
+
+        Args:
+            output_dir: Output directory to clean.
+            valid_names: Set of valid skill names (files to keep).
+
+        Returns:
+            List of removed file paths.
+        """
+        pass
+
+    def get_skills_dir(self, output_dir: Path) -> Path:
+        """Get the skills directory path for this adapter.
+
+        Returns the sibling skills/ directory relative to the adapter output.
+        E.g., for .windsurf/workflows/, returns .windsurf/skills/
+
+        Args:
+            output_dir: Base output directory.
+
+        Returns:
+            Path to the skills directory.
+        """
+        base = self.target_subdir.split("/")[0]  # e.g., ".windsurf" or ".github"
+        return output_dir / base / "skills"
+
+    def copy_skill(self, skill: SkillInfo, skills_dir: Path, show_progress: bool = False) -> Path:
+        """Copy a skill to the local skills directory with tracking metadata.
+
+        Uses unified copy interface (handles both local and remote).
+
+        Args:
+            skill: Skill to copy.
+            skills_dir: Target skills directory.
+            show_progress: If True, show progress for remote skills
+
+        Returns:
+            Path to the copied skill directory.
+        """
+        dest = skills_dir / skill.name
+
+        # Get the skill's content hash from manifest for tracking
+        # If manifest doesn't exist, skip tracking (graceful degradation)
+        inject_tracking = False
+        source_hash = None
+
+        try:
+            from manifest import load_manifest
+
+            manifest = load_manifest(skill.name)
+            if manifest:
+                source_hash = manifest.content_hash
+                inject_tracking = True
+        except Exception:
+            # Gracefully skip tracking if manifest cannot be loaded
+            pass
+
+        return copy_skill_unified(
+            skill.path,
+            dest,
+            validate=False,
+            show_progress=show_progress,
+            skill_name=skill.name,
+            inject_tracking=inject_tracking,
+            source_hash=source_hash,
+        )
+
+    def get_skill_path(self, skill: SkillInfo, output_dir: Path, copy: bool = True) -> str:
+        """Get the skill path to use in generated files.
+
+        Args:
+            skill: Skill information.
+            output_dir: Base output directory.
+            copy: Always True (skills are always copied now).
+
+        Returns:
+            Relative path string to use in adapter output.
+        """
+        # Always return relative path to local copy
+        return f"../skills/{skill.name}"
+
+    def generate_all(
+        self,
+        skills: list[SkillInfo],
+        output_dir: Path,
+        exclude: set[str] | None = None,
+        copy: bool = True,  # Always True, kept for backward compatibility
+    ) -> tuple[list[Path], list[Path]]:
+        """Generate files for all skills and cleanup stale ones.
+
+        Args:
+            skills: List of skills to generate.
+            output_dir: Base output directory.
+            exclude: Set of skill names to exclude.
+            copy: Always True (kept for backward compatibility).
+
+        Returns:
+            Tuple of (generated files, removed stale files).
+        """
+        exclude = exclude or set()
+        resolved_dir = self.resolve_output_dir(output_dir)
+        resolved_dir.mkdir(parents=True, exist_ok=True)
+
+        # Always copy skills (handles both local and remote)
+        skills_dir = self.get_skills_dir(output_dir)
+        skills_dir.mkdir(parents=True, exist_ok=True)
+
+        # Separate remote and local skills
+        from skillcopy.remote import is_remote_source
+
+        remote_skills = [(s, skills_dir / s.name) for s in skills if s.name not in exclude and is_remote_source(s.path)]
+        local_skills = [
+            (s, skills_dir / s.name) for s in skills if s.name not in exclude and not is_remote_source(s.path)
+        ]
+
+        failed_skills = []
+
+        # Copy remote skills in parallel
+        if remote_skills:
+            print(f"\nCopying {len(remote_skills)} remote skill(s)...", file=sys.stderr)
+            import threading
+            from concurrent.futures import ThreadPoolExecutor, as_completed
+
+            # Thread-safe print lock
+            print_lock = threading.Lock()
+
+            def copy_remote_with_progress(skill, dest):
+                """Copy a remote skill with thread-safe progress output."""
+                try:
+                    with print_lock:
+                        platform = (
+                            "GitHub"
+                            if "github.com" in skill.path
+                            else "GitLab"
+                            if "gitlab.com" in skill.path
+                            else "remote"
+                        )
+                        print(f"  ↓ {skill.name} (fetching from {platform}...)", file=sys.stderr, flush=True)
+
+                    self.copy_skill(skill, skills_dir, show_progress=False)  # We handle progress here
+
+                    with print_lock:
+                        print(f"  ✓ {skill.name} (downloaded)", file=sys.stderr)
+
+                    return skill.name, True, None
+                except Exception as e:
+                    with print_lock:
+                        print(f"  ✗ {skill.name} ({str(e)[:50]}...)", file=sys.stderr)
+                    return skill.name, False, str(e)
+
+            # Fetch remote skills in parallel (max 4 concurrent)
+            with ThreadPoolExecutor(max_workers=4) as executor:
+                futures = {
+                    executor.submit(copy_remote_with_progress, skill, dest): skill.name for skill, dest in remote_skills
+                }
+
+                for future in as_completed(futures):
+                    skill_name, success, error = future.result()
+                    if not success:
+                        failed_skills.append(skill_name)
+
+        # Copy local skills sequentially (fast anyway)
+        for skill, _dest in local_skills:
+            try:
+                self.copy_skill(skill, skills_dir, show_progress=False)
+            except Exception as e:
+                print(f"⚠ Warning: Failed to copy {skill.name}: {e}", file=sys.stderr)
+                failed_skills.append(skill.name)
+
+        generated = []
+        valid_names = set()
+
+        for skill in skills:
+            if skill.name in exclude:
+                continue
+
+            # Skip skills that failed to copy
+            if skill.name in failed_skills:
+                continue
+
+            valid_names.add(skill.name)
+            path = self.generate(skill, resolved_dir, copy=True, base_output_dir=output_dir)
+            generated.append(path)
+
+        removed = self.cleanup_stale(resolved_dir, valid_names)
+
+        return generated, removed