ai-agent-rules 0.15.2__py3-none-any.whl

ai_rules/agents/claude.py

@@ -0,0 +1,123 @@
+"""Claude Code agent implementation."""
+
+from functools import cached_property
+from pathlib import Path
+
+from ai_rules.agents.base import Agent
+from ai_rules.mcp import MCPManager, MCPStatus, OperationResult
+
+
+class ClaudeAgent(Agent):
+    """Agent for Claude Code configuration."""
+
+    DEPRECATED_SYMLINKS: list[Path] = [
+        Path("~/CLAUDE.md"),
+    ]
+
+    @property
+    def name(self) -> str:
+        return "Claude Code"
+
+    @property
+    def agent_id(self) -> str:
+        return "claude"
+
+    @property
+    def config_file_name(self) -> str:
+        return "settings.json"
+
+    @property
+    def config_file_format(self) -> str:
+        return "json"
+
+    @cached_property
+    def symlinks(self) -> list[tuple[Path, Path]]:
+        """Cached list of all Claude Code symlinks including dynamic agents/commands."""
+        result = []
+
+        result.append(
+            (Path("~/.claude/CLAUDE.md"), self.config_dir / "claude" / "CLAUDE.md")
+        )
+
+        settings_file = self.config_dir / "claude" / "settings.json"
+        if settings_file.exists():
+            target_file = self.config.get_settings_file_for_symlink(
+                "claude", settings_file
+            )
+            result.append((Path("~/.claude/settings.json"), target_file))
+
+        agents_dir = self.config_dir / "claude" / "agents"
+        if agents_dir.exists():
+            for agent_file in sorted(agents_dir.glob("*.md")):
+                result.append(
+                    (
+                        Path(f"~/.claude/agents/{agent_file.name}"),
+                        agent_file,
+                    )
+                )
+
+        commands_dir = self.config_dir / "claude" / "commands"
+        if commands_dir.exists():
+            for command_file in sorted(commands_dir.glob("*.md")):
+                result.append(
+                    (
+                        Path(f"~/.claude/commands/{command_file.name}"),
+                        command_file,
+                    )
+                )
+
+        skills_dir = self.config_dir / "claude" / "skills"
+        if skills_dir.exists():
+            for skill_folder in sorted(skills_dir.glob("*")):
+                if skill_folder.is_dir():
+                    result.append(
+                        (
+                            Path(f"~/.claude/skills/{skill_folder.name}"),
+                            skill_folder,
+                        )
+                    )
+
+        return result
+
+    def get_deprecated_symlinks(self) -> list[Path]:
+        """Return deprecated symlink locations for cleanup."""
+        return self.DEPRECATED_SYMLINKS
+
+    def install_mcps(
+        self, force: bool = False, dry_run: bool = False
+    ) -> tuple[OperationResult, str, list[str]]:
+        """Install managed MCPs into ~/.claude.json.
+
+        Args:
+            force: Skip confirmation prompts
+            dry_run: Don't actually modify files
+
+        Returns:
+            Tuple of (result, message, conflicts_list)
+        """
+        manager = MCPManager()
+        return manager.install_mcps(self.config_dir, self.config, force, dry_run)
+
+    def uninstall_mcps(
+        self, force: bool = False, dry_run: bool = False
+    ) -> tuple[OperationResult, str]:
+        """Uninstall managed MCPs from ~/.claude.json.
+
+        Args:
+            force: Skip confirmation prompts
+            dry_run: Don't actually modify files
+
+        Returns:
+            Tuple of (result, message)
+        """
+        manager = MCPManager()
+        return manager.uninstall_mcps(force, dry_run)
+
+    def get_mcp_status(self) -> MCPStatus:
+        """Get status of managed and unmanaged MCPs.
+
+        Returns:
+            MCPStatus object with categorized MCPs
+        """
+        manager = MCPManager()
+        return manager.get_status(self.config_dir, self.config)

ai_rules/agents/cursor.py

@@ -0,0 +1,70 @@
+"""Cursor editor agent implementation."""
+
+import sys
+
+from functools import cached_property
+from pathlib import Path
+
+from ai_rules.agents.base import Agent
+
+
+def _get_cursor_target_prefix() -> str:
+    """Get platform-specific Cursor config path with ~ prefix.
+
+    Returns:
+        Path string with ~ prefix for the current platform:
+        - macOS: ~/Library/Application Support/Cursor/User
+        - Windows: ~/AppData/Roaming/Cursor/User
+        - Linux/WSL: ~/.config/Cursor/User
+    """
+    if sys.platform == "darwin":
+        return "~/Library/Application Support/Cursor/User"
+    elif sys.platform == "win32":
+        return "~/AppData/Roaming/Cursor/User"
+    else:  # Linux/WSL
+        return "~/.config/Cursor/User"
+
+
+class CursorAgent(Agent):
+    """Agent for Cursor editor configuration."""
+
+    @property
+    def name(self) -> str:
+        return "Cursor"
+
+    @property
+    def agent_id(self) -> str:
+        return "cursor"
+
+    @property
+    def config_file_name(self) -> str:
+        return "settings.json"
+
+    @property
+    def config_file_format(self) -> str:
+        return "json"
+
+    @cached_property
+    def symlinks(self) -> list[tuple[Path, Path]]:
+        """Cached list of all Cursor symlinks.
+
+        Settings file uses cache-based approach with override merging.
+        Keybindings file uses direct symlink (array structure, no merging).
+        """
+        result = []
+        prefix = _get_cursor_target_prefix()
+
+        # Settings file - use cache if overrides exist
+        settings_file = self.config_dir / "cursor" / "settings.json"
+        if settings_file.exists():
+            target_file = self.config.get_settings_file_for_symlink(
+                "cursor", settings_file
+            )
+            result.append((Path(f"{prefix}/settings.json"), target_file))
+
+        # Keybindings file - direct symlink (no override merging for arrays)
+        keybindings_file = self.config_dir / "cursor" / "keybindings.json"
+        if keybindings_file.exists():
+            result.append((Path(f"{prefix}/keybindings.json"), keybindings_file))
+
+        return result

ai_rules/agents/goose.py

@@ -0,0 +1,47 @@
+"""Goose agent implementation."""
+
+from functools import cached_property
+from pathlib import Path
+
+from ai_rules.agents.base import Agent
+
+
+class GooseAgent(Agent):
+    """Agent for Goose configuration."""
+
+    @property
+    def name(self) -> str:
+        return "Goose"
+
+    @property
+    def agent_id(self) -> str:
+        return "goose"
+
+    @property
+    def config_file_name(self) -> str:
+        return "config.yaml"
+
+    @property
+    def config_file_format(self) -> str:
+        return "yaml"
+
+    @cached_property
+    def symlinks(self) -> list[tuple[Path, Path]]:
+        """Cached list of all Goose symlinks."""
+        result = []
+
+        result.append(
+            (
+                Path("~/.config/goose/.goosehints"),
+                self.config_dir / "goose" / ".goosehints",
+            )
+        )
+
+        config_file = self.config_dir / "goose" / "config.yaml"
+        if config_file.exists():
+            target_file = self.config.get_settings_file_for_symlink(
+                "goose", config_file
+            )
+            result.append((Path("~/.config/goose/config.yaml"), target_file))
+
+        return result

ai_rules/agents/shared.py

@@ -0,0 +1,35 @@
+"""Shared agent implementation for agent-agnostic configurations."""
+
+from functools import cached_property
+from pathlib import Path
+
+from ai_rules.agents.base import Agent
+
+
+class SharedAgent(Agent):
+    """Agent for shared configurations that both Claude Code and Goose respect."""
+
+    @property
+    def name(self) -> str:
+        return "Shared"
+
+    @property
+    def agent_id(self) -> str:
+        return "shared"
+
+    @property
+    def config_file_name(self) -> str:
+        return ""
+
+    @property
+    def config_file_format(self) -> str:
+        return ""
+
+    @cached_property
+    def symlinks(self) -> list[tuple[Path, Path]]:
+        """Cached list of shared symlinks for agent-agnostic configurations."""
+        result = []
+
+        result.append((Path("~/AGENTS.md"), self.config_dir / "AGENTS.md"))
+
+        return result

ai_rules/bootstrap/__init__.py

@@ -0,0 +1,75 @@
+"""Bootstrap module for system-wide installation and auto-update functionality.
+
+This module provides utilities for:
+- Installing tools via uv (PyPI-based)
+- Checking for and applying updates from PyPI
+- Managing auto-update configuration
+
+Designed to be self-contained and easily extractable for use in other projects.
+"""
+
+from .config import (
+    AutoUpdateConfig,
+    clear_all_pending_updates,
+    clear_pending_update,
+    get_config_dir,
+    get_config_path,
+    get_pending_update_path,
+    load_all_pending_updates,
+    load_auto_update_config,
+    load_pending_update,
+    save_auto_update_config,
+    save_pending_update,
+    should_check_now,
+)
+from .installer import (
+    UV_NOT_FOUND_ERROR,
+    ensure_statusline_installed,
+    get_tool_config_dir,
+    get_tool_version,
+    install_tool,
+    is_command_available,
+    uninstall_tool,
+)
+from .updater import (
+    UPDATABLE_TOOLS,
+    ToolSpec,
+    UpdateInfo,
+    check_index_updates,
+    check_tool_updates,
+    get_tool_by_id,
+    perform_pypi_update,
+)
+from .version import get_package_version, is_newer, parse_version
+
+__all__ = [
+    "get_package_version",
+    "is_newer",
+    "parse_version",
+    "UV_NOT_FOUND_ERROR",
+    "ensure_statusline_installed",
+    "get_tool_config_dir",
+    "get_tool_version",
+    "install_tool",
+    "is_command_available",
+    "uninstall_tool",
+    "UPDATABLE_TOOLS",
+    "ToolSpec",
+    "UpdateInfo",
+    "check_index_updates",
+    "check_tool_updates",
+    "get_tool_by_id",
+    "perform_pypi_update",
+    "AutoUpdateConfig",
+    "clear_all_pending_updates",
+    "clear_pending_update",
+    "get_config_dir",
+    "get_config_path",
+    "get_pending_update_path",
+    "load_all_pending_updates",
+    "load_auto_update_config",
+    "load_pending_update",
+    "save_auto_update_config",
+    "save_pending_update",
+    "should_check_now",
+]

ai_rules/bootstrap/config.py

@@ -0,0 +1,261 @@
+"""Auto-update configuration management."""
+
+import dataclasses
+import json
+import logging
+import re
+
+from dataclasses import asdict, dataclass
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from .updater import UpdateInfo
+
+logger = logging.getLogger(__name__)
+
+
+def _validate_tool_id(tool_id: str) -> bool:
+    """Validate tool_id contains only safe characters."""
+    return bool(re.match(r"^[a-z0-9][a-z0-9_-]*$", tool_id))
+
+
+@dataclass
+class AutoUpdateConfig:
+    """Configuration for automatic update checks."""
+
+    enabled: bool = True
+    frequency: str = "daily"  # daily, weekly, never
+    last_check: str | None = None  # ISO format timestamp
+    notify_only: bool = False
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "AutoUpdateConfig":
+        """Create from dict, using dataclass defaults for missing keys."""
+        fields = {f.name for f in dataclasses.fields(cls)}
+        kwargs = {k: v for k, v in data.items() if k in fields}
+        return cls(**kwargs)
+
+
+def get_config_dir(package_name: str = "ai-rules") -> Path:
+    """Get the config directory for the package.
+
+    Args:
+        package_name: Name of the package
+
+    Returns:
+        Path to config directory (e.g., ~/.ai-rules/)
+    """
+    config_dir = Path.home() / f".{package_name}"
+    config_dir.mkdir(parents=True, exist_ok=True)
+    return config_dir
+
+
+def get_config_path(package_name: str = "ai-rules") -> Path:
+    """Get path to bootstrap config file.
+
+    Args:
+        package_name: Name of the package
+
+    Returns:
+        Path to update_config.yaml
+    """
+    return get_config_dir(package_name) / "update_config.yaml"
+
+
+def load_auto_update_config(package_name: str = "ai-rules") -> AutoUpdateConfig:
+    """Load auto-update configuration.
+
+    Args:
+        package_name: Name of the package
+
+    Returns:
+        AutoUpdateConfig with loaded or default values
+    """
+    config_path = get_config_path(package_name)
+
+    if not config_path.exists():
+        return AutoUpdateConfig()
+
+    try:
+        with open(config_path) as f:
+            data = yaml.safe_load(f) or {}
+        return AutoUpdateConfig.from_dict(data)
+    except (yaml.YAMLError, OSError):
+        return AutoUpdateConfig()
+
+
+def save_auto_update_config(
+    config: AutoUpdateConfig, package_name: str = "ai-rules"
+) -> None:
+    """Save auto-update configuration.
+
+    Args:
+        config: Configuration to save
+        package_name: Name of the package
+    """
+    config_path = get_config_path(package_name)
+
+    try:
+        with open(config_path, "w") as f:
+            yaml.dump(asdict(config), f, default_flow_style=False, sort_keys=False)
+    except OSError as e:
+        logger.debug(f"Failed to save config to {config_path}: {e}")
+
+
+def should_check_now(config: AutoUpdateConfig) -> bool:
+    """Determine if update check is due based on frequency.
+
+    Args:
+        config: Auto-update configuration
+
+    Returns:
+        True if check should be performed, False otherwise
+    """
+    if not config.enabled:
+        return False
+
+    if config.frequency == "never":
+        return False
+
+    if not config.last_check:
+        return True
+
+    try:
+        last_check = datetime.fromisoformat(config.last_check)
+        now = datetime.now()
+
+        if config.frequency == "daily":
+            return now - last_check > timedelta(days=1)
+        elif config.frequency == "weekly":
+            return now - last_check > timedelta(days=7)
+
+    except (ValueError, TypeError):
+        return True
+
+    return False
+
+
+def get_pending_update_path(tool_id: str = "ai-rules") -> Path:
+    """Get path to pending update cache file for a specific tool.
+
+    Args:
+        tool_id: Tool identifier (e.g., "ai-rules", "statusline")
+
+    Returns:
+        Path to pending update JSON file
+
+    Raises:
+        ValueError: If tool_id contains invalid characters
+    """
+    if not _validate_tool_id(tool_id):
+        raise ValueError(f"Invalid tool_id: {tool_id}")
+
+    if tool_id == "ai-rules":
+        filename = "pending_update.json"
+    else:
+        filename = f"pending_{tool_id}_update.json"
+
+    return get_config_dir("ai-rules") / filename
+
+
+def load_pending_update(tool_id: str = "ai-rules") -> UpdateInfo | None:
+    """Load cached update info from previous background check.
+
+    Args:
+        tool_id: Tool identifier (e.g., "ai-rules", "statusline")
+
+    Returns:
+        UpdateInfo if available, None otherwise
+    """
+    if not _validate_tool_id(tool_id):
+        return None
+
+    pending_path = get_pending_update_path(tool_id)
+
+    if not pending_path.exists():
+        return None
+
+    try:
+        with open(pending_path) as f:
+            data = json.load(f)
+
+        return UpdateInfo(
+            has_update=data.get("has_update", False),
+            current_version=data["current_version"],
+            latest_version=data["latest_version"],
+            source=data["source"],
+        )
+    except (json.JSONDecodeError, KeyError, OSError):
+        return None
+
+
+def save_pending_update(info: UpdateInfo, tool_id: str = "ai-rules") -> None:
+    """Save update info for next session.
+
+    Args:
+        info: Update information to save
+        tool_id: Tool identifier (e.g., "ai-rules", "statusline")
+    """
+    if not _validate_tool_id(tool_id):
+        return
+
+    pending_path = get_pending_update_path(tool_id)
+
+    try:
+        data = {
+            "has_update": info.has_update,
+            "current_version": info.current_version,
+            "latest_version": info.latest_version,
+            "source": info.source,
+            "checked_at": datetime.now().isoformat(),
+        }
+
+        with open(pending_path, "w") as f:
+            json.dump(data, f, indent=2)
+    except OSError as e:
+        logger.debug(f"Failed to save pending update to {pending_path}: {e}")
+
+
+def clear_pending_update(tool_id: str = "ai-rules") -> None:
+    """Clear pending update after user action.
+
+    Args:
+        tool_id: Tool identifier (e.g., "ai-rules", "statusline")
+    """
+    if not _validate_tool_id(tool_id):
+        return
+
+    pending_path = get_pending_update_path(tool_id)
+
+    try:
+        pending_path.unlink(missing_ok=True)
+    except OSError as e:
+        logger.debug(f"Failed to delete pending update at {pending_path}: {e}")
+
+
+def load_all_pending_updates() -> dict[str, UpdateInfo]:
+    """Load pending updates for all tools.
+
+    Returns:
+        Dictionary mapping tool_id to UpdateInfo for tools with pending updates
+    """
+    from .updater import UPDATABLE_TOOLS
+
+    result = {}
+    for tool in UPDATABLE_TOOLS:
+        pending = load_pending_update(tool.tool_id)
+        if pending and pending.has_update:
+            result[tool.tool_id] = pending
+
+    return result
+
+
+def clear_all_pending_updates() -> None:
+    """Clear pending updates for all tools."""
+    from .updater import UPDATABLE_TOOLS
+
+    for tool in UPDATABLE_TOOLS:
+        clear_pending_update(tool.tool_id)