loadout 0.3.0__py3-none-any.whl

loadout/__init__.py

@@ -0,0 +1,66 @@
+"""loadout - Install artifacts into coding agents."""
+
+from loadout._version import __version__
+from loadout.adapters import AgentAdapter, ClaudeCodeAdapter, CursorAdapter, OpenCodeAdapter
+from loadout.callbacks import LoadoutCallbacks, NoOpCallbacks
+from loadout.discovery import detect_agents, discover_artifacts
+from loadout.exceptions import (
+    AdapterAlreadyRegisteredError,
+    AdapterNotFoundError,
+    ArtifactNotFoundError,
+    InstallError,
+    LoadoutError,
+    ManifestError,
+    TransformError,
+)
+from loadout.installer import install, install_all, install_interactive
+from loadout.models import (
+    Artifact,
+    ArtifactFrontmatter,
+    ArtifactType,
+    DetectedAgent,
+    InstallResult,
+    InstallStatus,
+    InstallSummary,
+    Manifest,
+)
+from loadout.registry import AdapterRegistry, get_default_registry
+
+__all__ = [
+    "__version__",
+    # Adapters
+    "AgentAdapter",
+    "ClaudeCodeAdapter",
+    "CursorAdapter",
+    "OpenCodeAdapter",
+    # Callbacks
+    "LoadoutCallbacks",
+    "NoOpCallbacks",
+    # Discovery
+    "detect_agents",
+    "discover_artifacts",
+    # Exceptions
+    "AdapterAlreadyRegisteredError",
+    "AdapterNotFoundError",
+    "ArtifactNotFoundError",
+    "InstallError",
+    "LoadoutError",
+    "ManifestError",
+    "TransformError",
+    # Installer
+    "install",
+    "install_all",
+    "install_interactive",
+    # Models
+    "Artifact",
+    "ArtifactFrontmatter",
+    "ArtifactType",
+    "DetectedAgent",
+    "InstallResult",
+    "InstallStatus",
+    "InstallSummary",
+    "Manifest",
+    # Registry
+    "AdapterRegistry",
+    "get_default_registry",
+]

loadout/_prompts.py

@@ -0,0 +1,44 @@
+"""Built-in interactive prompts (requires questionary)."""
+
+from __future__ import annotations
+
+from loadout.models import DetectedAgent
+
+
+def prompt_agent_selection(agents: list[DetectedAgent]) -> list[DetectedAgent]:
+    """Present a checkbox prompt for agent selection.
+
+    Requires the `questionary` package (install with `loadout[interactive]`).
+
+    Args:
+        agents: Available agents to choose from.
+
+    Returns:
+        List of selected agents.
+
+    Raises:
+        ImportError: If questionary is not installed.
+    """
+    try:
+        import questionary
+    except ImportError:
+        raise ImportError(
+            "questionary is required for interactive prompts. "
+            "Install it with: pip install loadout[interactive]"
+        ) from None
+
+    choices = [
+        questionary.Choice(
+            title=agent.display_name or agent.name,
+            value=agent,
+            checked=True,
+        )
+        for agent in agents
+    ]
+
+    selected = questionary.checkbox(
+        "Select agents to install to:",
+        choices=choices,
+    ).ask()
+
+    return selected or []

loadout/_transforms.py

@@ -0,0 +1,77 @@
+"""Frontmatter parsing and content transformation utilities."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+import yaml
+
+from loadout.exceptions import TransformError
+from loadout.models import ArtifactFrontmatter
+
+_FRONTMATTER_RE = re.compile(r"^---\s*\n(.*?)---\s*\n?", re.DOTALL)
+
+
+def parse_frontmatter(content: str) -> tuple[ArtifactFrontmatter, str]:
+    """Parse YAML frontmatter from markdown content.
+
+    Returns the parsed frontmatter and the remaining body content.
+    """
+    match = _FRONTMATTER_RE.match(content)
+    if not match:
+        return ArtifactFrontmatter(), content
+
+    try:
+        raw: dict[str, Any] = yaml.safe_load(match.group(1)) or {}
+    except yaml.YAMLError as e:
+        raise TransformError(f"Invalid YAML frontmatter: {e}") from e
+
+    body = content[match.end() :]
+
+    known_keys = {"description", "always_apply", "alwaysApply", "globs"}
+    extra = {k: v for k, v in raw.items() if k not in known_keys}
+
+    globs_val = raw.get("globs", [])
+    if isinstance(globs_val, str):
+        globs_val = [globs_val]
+
+    fm = ArtifactFrontmatter(
+        description=raw.get("description", ""),
+        always_apply=raw.get("always_apply", raw.get("alwaysApply", False)),
+        globs=globs_val,
+        extra=extra,
+    )
+
+    return fm, body
+
+
+def strip_frontmatter(content: str) -> str:
+    """Remove YAML frontmatter from markdown content."""
+    match = _FRONTMATTER_RE.match(content)
+    if not match:
+        return content
+    return content[match.end() :]
+
+
+def add_cursor_frontmatter(
+    content: str,
+    description: str = "",
+    always_apply: bool = False,
+    globs: list[str] | None = None,
+) -> str:
+    """Add or replace frontmatter in Cursor .mdc format.
+
+    Cursor rules require description and alwaysApply fields.
+    """
+    _, body = parse_frontmatter(content)
+
+    fm_dict: dict[str, Any] = {
+        "description": description,
+        "alwaysApply": always_apply,
+    }
+    if globs:
+        fm_dict["globs"] = globs
+
+    fm_yaml = yaml.dump(fm_dict, default_flow_style=False, sort_keys=False).strip()
+    return f"---\n{fm_yaml}\n---\n{body}"

loadout/_version.py

@@ -0,0 +1 @@
+__version__ = "0.3.0"

loadout/adapters/__init__.py

@@ -0,0 +1,13 @@
+"""Built-in agent adapters."""
+
+from loadout.adapters._protocol import AgentAdapter
+from loadout.adapters.claude import ClaudeCodeAdapter
+from loadout.adapters.cursor import CursorAdapter
+from loadout.adapters.opencode import OpenCodeAdapter
+
+__all__ = [
+    "AgentAdapter",
+    "ClaudeCodeAdapter",
+    "CursorAdapter",
+    "OpenCodeAdapter",
+]

loadout/adapters/_base.py

@@ -0,0 +1,144 @@
+"""Shared base adapter with common file-copy logic."""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+from loadout.adapters._protocol import AgentAdapter
+from loadout.models import (
+    Artifact,
+    ArtifactType,
+    DetectedAgent,
+    InstallResult,
+    InstallStatus,
+)
+
+
+class _BaseFileAdapter(AgentAdapter):
+    """Base adapter with shared file-copy/install logic.
+
+    Concrete adapters only need to override identity properties,
+    supported types, path resolution, and transforms.
+    """
+
+    def detect(self) -> DetectedAgent | None:
+        config_dir = Path.home() / self.config_dir_name
+        if config_dir.is_dir():
+            return DetectedAgent(
+                name=self.agent_name,
+                config_dir=config_dir,
+                display_name=self.display_name,
+            )
+        return None
+
+    def transform_content(self, artifact: Artifact, content: str) -> str:
+        return content
+
+    def transform_filename(self, artifact: Artifact, filename: str) -> str:
+        return filename
+
+    def install(
+        self, artifact: Artifact, agent: DetectedAgent, force: bool = False
+    ) -> InstallResult:
+        if artifact.artifact_type not in self.supported_artifact_types():
+            return InstallResult(
+                artifact=artifact,
+                agent=agent,
+                status=InstallStatus.SKIPPED,
+                error=(
+                    f"{self.display_name} does not support"
+                    f" {artifact.artifact_type.value} artifacts"
+                ),
+            )
+
+        try:
+            target_path = self.get_target_path(artifact, agent.config_dir)
+
+            if target_path.exists() and not force:
+                return InstallResult(
+                    artifact=artifact,
+                    agent=agent,
+                    status=InstallStatus.ALREADY_EXISTS,
+                    target_path=target_path,
+                )
+
+            target_path.parent.mkdir(parents=True, exist_ok=True)
+
+            source = artifact.source_path
+            if source.is_dir():
+                return self._install_directory(artifact, agent, source, target_path, force)
+            else:
+                return self._install_file(artifact, agent, source, target_path)
+
+        except Exception as e:
+            return InstallResult(
+                artifact=artifact,
+                agent=agent,
+                status=InstallStatus.FAILED,
+                error=str(e),
+            )
+
+    def _install_file(
+        self,
+        artifact: Artifact,
+        agent: DetectedAgent,
+        source: Path,
+        target_path: Path,
+    ) -> InstallResult:
+        content = source.read_text(encoding="utf-8")
+        transformed = self.transform_content(artifact, content)
+
+        final_name = self.transform_filename(artifact, target_path.name)
+        final_path = target_path.parent / final_name
+
+        final_path.write_text(transformed, encoding="utf-8")
+
+        return InstallResult(
+            artifact=artifact,
+            agent=agent,
+            status=InstallStatus.INSTALLED,
+            target_path=final_path,
+        )
+
+    def _install_directory(
+        self,
+        artifact: Artifact,
+        agent: DetectedAgent,
+        source: Path,
+        target_path: Path,
+        force: bool,
+    ) -> InstallResult:
+        if target_path.exists() and force:
+            shutil.rmtree(target_path)
+
+        target_path.mkdir(parents=True, exist_ok=True)
+
+        for src_file in source.rglob("*"):
+            if src_file.is_file():
+                rel = src_file.relative_to(source)
+                dst_file = target_path / rel
+                dst_file.parent.mkdir(parents=True, exist_ok=True)
+
+                content = src_file.read_text(encoding="utf-8")
+                transformed = self.transform_content(artifact, content)
+
+                final_name = self.transform_filename(artifact, dst_file.name)
+                final_path = dst_file.parent / final_name
+                final_path.write_text(transformed, encoding="utf-8")
+
+        return InstallResult(
+            artifact=artifact,
+            agent=agent,
+            status=InstallStatus.INSTALLED,
+            target_path=target_path,
+        )
+
+    def _get_artifact_subdir(self, artifact_type: ArtifactType) -> str:
+        """Map artifact type to subdirectory name."""
+        return {
+            ArtifactType.SKILL: "skills",
+            ArtifactType.RULE: "rules",
+            ArtifactType.AGENT: "agents",
+            ArtifactType.COMMAND: "commands",
+        }[artifact_type]

loadout/adapters/_protocol.py

@@ -0,0 +1,61 @@
+"""Agent adapter abstract base class."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+from loadout.models import Artifact, ArtifactType, DetectedAgent, InstallResult
+
+
+class AgentAdapter(ABC):
+    """Abstract base class for coding agent adapters.
+
+    Each supported agent (Claude Code, Cursor, OpenCode, etc.) implements
+    this interface. The adapter handles detection, path resolution,
+    content transformation, and installation for its agent.
+    """
+
+    @property
+    @abstractmethod
+    def agent_name(self) -> str:
+        """Unique identifier for this agent (e.g. 'claude', 'cursor')."""
+
+    @property
+    @abstractmethod
+    def display_name(self) -> str:
+        """Human-readable name (e.g. 'Claude Code', 'Cursor')."""
+
+    @property
+    @abstractmethod
+    def config_dir_name(self) -> str:
+        """Name of the config directory (e.g. '.claude', '.cursor')."""
+
+    @abstractmethod
+    def supported_artifact_types(self) -> set[ArtifactType]:
+        """Return the set of artifact types this agent supports."""
+
+    @abstractmethod
+    def detect(self) -> DetectedAgent | None:
+        """Detect if this agent is installed on the system.
+
+        Returns a DetectedAgent if found, None otherwise.
+        """
+
+    @abstractmethod
+    def get_target_path(self, artifact: Artifact, config_dir: Path) -> Path:
+        """Resolve the target installation path for an artifact."""
+
+    @abstractmethod
+    def transform_content(self, artifact: Artifact, content: str) -> str:
+        """Transform artifact content for this agent's format."""
+
+    @abstractmethod
+    def transform_filename(self, artifact: Artifact, filename: str) -> str:
+        """Transform artifact filename for this agent's format."""
+
+    @abstractmethod
+    def install(
+        self, artifact: Artifact, agent: DetectedAgent, force: bool = False
+    ) -> InstallResult:
+        """Install an artifact to this agent."""

loadout/adapters/claude.py

@@ -0,0 +1,44 @@
+"""Claude Code adapter."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from loadout.adapters._base import _BaseFileAdapter
+from loadout.models import Artifact, ArtifactType
+
+
+class ClaudeCodeAdapter(_BaseFileAdapter):
+    """Adapter for Claude Code (~/.claude/)."""
+
+    @property
+    def agent_name(self) -> str:
+        return "claude"
+
+    @property
+    def display_name(self) -> str:
+        return "Claude Code"
+
+    @property
+    def config_dir_name(self) -> str:
+        return ".claude"
+
+    def supported_artifact_types(self) -> set[ArtifactType]:
+        return {ArtifactType.SKILL, ArtifactType.RULE, ArtifactType.AGENT, ArtifactType.COMMAND}
+
+    def get_target_path(self, artifact: Artifact, config_dir: Path) -> Path:
+        subdir = self._get_artifact_subdir(artifact.artifact_type)
+
+        if artifact.artifact_type == ArtifactType.SKILL:
+            # skills/<name>/ (directory)
+            return config_dir / subdir / artifact.name
+
+        if artifact.category:
+            # rules/<category>/<name>.md, agents/<category>/<name>.md
+            return config_dir / subdir / artifact.category / f"{artifact.name}.md"
+
+        if artifact.artifact_type == ArtifactType.COMMAND:
+            # commands/<name>.md
+            return config_dir / subdir / f"{artifact.name}.md"
+
+        return config_dir / subdir / f"{artifact.name}.md"

loadout/adapters/cursor.py

@@ -0,0 +1,60 @@
+"""Cursor adapter with .mdc format transformation."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from loadout._transforms import add_cursor_frontmatter, parse_frontmatter
+from loadout.adapters._base import _BaseFileAdapter
+from loadout.models import Artifact, ArtifactType
+
+
+class CursorAdapter(_BaseFileAdapter):
+    """Adapter for Cursor (~/.cursor/).
+
+    Cursor rules use .mdc format with description/alwaysApply frontmatter.
+    Skills are installed as-is.
+    """
+
+    @property
+    def agent_name(self) -> str:
+        return "cursor"
+
+    @property
+    def display_name(self) -> str:
+        return "Cursor"
+
+    @property
+    def config_dir_name(self) -> str:
+        return ".cursor"
+
+    def supported_artifact_types(self) -> set[ArtifactType]:
+        return {ArtifactType.SKILL, ArtifactType.RULE}
+
+    def get_target_path(self, artifact: Artifact, config_dir: Path) -> Path:
+        subdir = self._get_artifact_subdir(artifact.artifact_type)
+
+        if artifact.artifact_type == ArtifactType.SKILL:
+            return config_dir / subdir / artifact.name
+
+        if artifact.category:
+            return config_dir / subdir / artifact.category / f"{artifact.name}.mdc"
+
+        return config_dir / subdir / f"{artifact.name}.mdc"
+
+    def transform_content(self, artifact: Artifact, content: str) -> str:
+        if artifact.artifact_type != ArtifactType.RULE:
+            return content
+
+        fm, _ = parse_frontmatter(content)
+        return add_cursor_frontmatter(
+            content,
+            description=fm.description,
+            always_apply=fm.always_apply,
+            globs=fm.globs if fm.globs else None,
+        )
+
+    def transform_filename(self, artifact: Artifact, filename: str) -> str:
+        if artifact.artifact_type == ArtifactType.RULE and filename.endswith(".md"):
+            return filename[:-3] + ".mdc"
+        return filename

loadout/adapters/opencode.py

@@ -0,0 +1,36 @@
+"""OpenCode adapter."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from loadout.adapters._base import _BaseFileAdapter
+from loadout.models import Artifact, ArtifactType
+
+
+class OpenCodeAdapter(_BaseFileAdapter):
+    """Adapter for OpenCode (~/.opencode/)."""
+
+    @property
+    def agent_name(self) -> str:
+        return "opencode"
+
+    @property
+    def display_name(self) -> str:
+        return "OpenCode"
+
+    @property
+    def config_dir_name(self) -> str:
+        return ".opencode"
+
+    def supported_artifact_types(self) -> set[ArtifactType]:
+        return {ArtifactType.SKILL, ArtifactType.COMMAND}
+
+    def get_target_path(self, artifact: Artifact, config_dir: Path) -> Path:
+        subdir = self._get_artifact_subdir(artifact.artifact_type)
+
+        if artifact.artifact_type == ArtifactType.SKILL:
+            return config_dir / subdir / artifact.name
+
+        # commands/<name>.md
+        return config_dir / subdir / f"{artifact.name}.md"

loadout/callbacks.py

@@ -0,0 +1,51 @@
+"""Callback protocol for lifecycle events during installation."""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from loadout.models import Artifact, DetectedAgent, InstallResult
+
+
+@runtime_checkable
+class LoadoutCallbacks(Protocol):
+    """Protocol for receiving lifecycle events during installation.
+
+    CLIs implement this to provide custom messaging/progress.
+    All methods have default no-op behavior so implementers
+    only need to override the hooks they care about.
+    """
+
+    def on_artifact_discovered(self, artifact: Artifact) -> None: ...
+
+    def on_agent_detected(self, agent: DetectedAgent) -> None: ...
+
+    def on_install_started(self, artifact: Artifact, agent: DetectedAgent) -> None: ...
+
+    def on_install_complete(self, result: InstallResult) -> None: ...
+
+    def on_install_skipped(self, result: InstallResult) -> None: ...
+
+    def on_install_failed(self, result: InstallResult) -> None: ...
+
+
+class NoOpCallbacks:
+    """Default no-op implementation of LoadoutCallbacks."""
+
+    def on_artifact_discovered(self, artifact: Artifact) -> None:
+        pass
+
+    def on_agent_detected(self, agent: DetectedAgent) -> None:
+        pass
+
+    def on_install_started(self, artifact: Artifact, agent: DetectedAgent) -> None:
+        pass
+
+    def on_install_complete(self, result: InstallResult) -> None:
+        pass
+
+    def on_install_skipped(self, result: InstallResult) -> None:
+        pass
+
+    def on_install_failed(self, result: InstallResult) -> None:
+        pass