ai-agent-rules 0.11.0__py3-none-any.whl → 0.15.8__py3-none-any.whl

ai_rules/config.py

@@ -12,6 +12,8 @@ from typing import Any
 
 import yaml
 
+from ai_rules.utils import deep_merge
+
 __all__ = [
     "Config",
     "AGENT_CONFIG_METADATA",
@@ -25,6 +27,10 @@ AGENT_CONFIG_METADATA = {
         "config_file": "settings.json",
         "format": "json",
     },
+    "cursor": {
+        "config_file": "settings.json",
+        "format": "json",
+    },
     "goose": {
         "config_file": "config.yaml",
         "format": "yaml",
@@ -244,40 +250,65 @@ class Config:
         exclude_symlinks: list[str] | None = None,
         settings_overrides: dict[str, dict[str, Any]] | None = None,
         mcp_overrides: dict[str, dict[str, Any]] | None = None,
+        profile_name: str | None = None,
     ):
         self.exclude_symlinks = set(exclude_symlinks or [])
         self.settings_overrides = settings_overrides or {}
         self.mcp_overrides = mcp_overrides or {}
+        self.profile_name = profile_name
 
     @classmethod
-    @lru_cache(maxsize=1)
-    def load(cls) -> "Config":
-        """Load configuration from ~/.ai-rules-config.yaml.
+    def load(cls, profile: str | None = None) -> "Config":
+        """Load configuration from profile and ~/.ai-rules-config.yaml.
 
-        Cached to avoid redundant YAML parsing within a single CLI invocation.
+        Merge order (lowest to highest priority):
+        1. Profile overrides (if profile specified, defaults to "default")
+        2. Local overrides from ~/.ai-rules-config.yaml
 
-        Returns empty config if file doesn't exist.
+        Args:
+            profile: Optional profile name to load (default: "default")
 
-        Note: Repo-level config support was removed in v0.5.0.
-        All configuration is now user-specific.
+        Returns:
+            Config instance with merged overrides
         """
-        user_config_path = Path.home() / ".ai-rules-config.yaml"
+        return cls._load_cached(profile or "default")
 
-        exclude_symlinks = []
-        settings_overrides = {}
-        mcp_overrides = {}
+    @classmethod
+    @lru_cache(maxsize=8)
+    def _load_cached(cls, profile_name: str) -> "Config":
+        """Internal cached loader keyed by profile name."""
+        from ai_rules.profiles import ProfileLoader, ProfileNotFoundError
+
+        loader = ProfileLoader()
+
+        try:
+            profile_data = loader.load_profile(profile_name)
+        except ProfileNotFoundError:
+            raise
+
+        exclude_symlinks = list(profile_data.exclude_symlinks)
+        settings_overrides = copy.deepcopy(profile_data.settings_overrides)
+        mcp_overrides = copy.deepcopy(profile_data.mcp_overrides)
 
+        user_config_path = Path.home() / ".ai-rules-config.yaml"
         if user_config_path.exists():
             with open(user_config_path) as f:
-                data = yaml.safe_load(f) or {}
-                exclude_symlinks = data.get("exclude_symlinks", [])
-                settings_overrides = data.get("settings_overrides", {})
-                mcp_overrides = data.get("mcp_overrides", {})
+                user_data = yaml.safe_load(f) or {}
+
+            user_excludes = user_data.get("exclude_symlinks", [])
+            exclude_symlinks = list(set(exclude_symlinks) | set(user_excludes))
+
+            user_settings = user_data.get("settings_overrides", {})
+            settings_overrides = deep_merge(settings_overrides, user_settings)
+
+            user_mcp = user_data.get("mcp_overrides", {})
+            mcp_overrides = deep_merge(mcp_overrides, user_mcp)
 
         return cls(
             exclude_symlinks=exclude_symlinks,
             settings_overrides=settings_overrides,
             mcp_overrides=mcp_overrides,
+            profile_name=profile_name,
         )
 
     def is_excluded(self, symlink_target: str) -> bool:
@@ -301,36 +332,6 @@ class Config:
         cache_dir.mkdir(parents=True, exist_ok=True)
         return cache_dir
 
-    @staticmethod
-    def _deep_merge(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
-        """Deep merge two dictionaries, with override values taking precedence.
-
-        Supports merging nested dictionaries and arrays. Arrays are merged element-by-element,
-        with dict elements being recursively merged.
-
-        Uses deep copy to prevent mutation of the base dictionary.
-        """
-        result = copy.deepcopy(base)
-        for key, value in override.items():
-            if key not in result:
-                result[key] = value
-            elif isinstance(result[key], dict) and isinstance(value, dict):
-                result[key] = Config._deep_merge(result[key], value)
-            elif isinstance(result[key], list) and isinstance(value, list):
-                merged_array = copy.deepcopy(result[key])
-                for i, item in enumerate(value):
-                    if i < len(merged_array):
-                        if isinstance(merged_array[i], dict) and isinstance(item, dict):
-                            merged_array[i] = Config._deep_merge(merged_array[i], item)
-                        else:
-                            merged_array[i] = item
-                    else:
-                        merged_array.append(item)
-                result[key] = merged_array
-            else:
-                result[key] = value
-        return result
-
     def merge_settings(
         self, agent: str, base_settings: dict[str, Any]
     ) -> dict[str, Any]:
@@ -346,7 +347,7 @@ class Config:
         if agent not in self.settings_overrides:
             return base_settings
 
-        return self._deep_merge(base_settings, self.settings_overrides[agent])
+        return deep_merge(base_settings, self.settings_overrides[agent])
 
     def get_merged_settings_path(self, agent: str) -> Path | None:
         """Get the path to cached merged settings for an agent.
@@ -429,6 +430,14 @@ class Config:
             if user_config_path.stat().st_mtime > cache_mtime:
                 return True
 
+        if self.profile_name and self.profile_name != "default":
+            from ai_rules.profiles import ProfileLoader
+
+            loader = ProfileLoader()
+            profile_path = loader._profiles_dir / f"{self.profile_name}.yaml"
+            if profile_path.exists() and profile_path.stat().st_mtime > cache_mtime:
+                return True
+
         return False
 
     def get_cache_diff(self, agent: str, base_settings_path: Path) -> str | None:

ai_rules/mcp.py

@@ -12,6 +12,7 @@ from pathlib import Path
 from typing import Any, cast
 
 from .config import Config
+from .utils import deep_merge
 
 
 class OperationResult(Enum):
@@ -66,9 +67,7 @@ class MCPManager:
         merged_mcps = {}
         for name, _mcp_config in {**base_mcps, **mcp_overrides}.items():
             if name in base_mcps and name in mcp_overrides:
-                merged_mcps[name] = Config._deep_merge(
-                    base_mcps[name], mcp_overrides[name]
-                )
+                merged_mcps[name] = deep_merge(base_mcps[name], mcp_overrides[name])
             elif name in base_mcps:
                 merged_mcps[name] = copy.deepcopy(base_mcps[name])
             else:

ai_rules/profiles.py

@@ -0,0 +1,187 @@
+"""Profile loading and inheritance resolution."""
+
+from dataclasses import dataclass, field
+from importlib.resources import files as resource_files
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from ai_rules.utils import deep_merge
+
+
+@dataclass
+class Profile:
+    """A named collection of configuration overrides."""
+
+    name: str
+    description: str = ""
+    extends: str | None = None
+    settings_overrides: dict[str, dict[str, Any]] = field(default_factory=dict)
+    exclude_symlinks: list[str] = field(default_factory=list)
+    mcp_overrides: dict[str, dict[str, Any]] = field(default_factory=dict)
+
+
+class ProfileError(Exception):
+    """Base exception for profile-related errors."""
+
+    pass
+
+
+class ProfileNotFoundError(ProfileError):
+    """Raised when a profile is not found."""
+
+    pass
+
+
+class CircularInheritanceError(ProfileError):
+    """Raised when circular profile inheritance is detected."""
+
+    pass
+
+
+class ProfileLoader:
+    """Loads and resolves profile inheritance."""
+
+    def __init__(self, profiles_dir: Path | None = None):
+        """Initialize profile loader.
+
+        Args:
+            profiles_dir: Optional override for profiles directory (for testing)
+        """
+        if profiles_dir:
+            self._profiles_dir = profiles_dir
+        else:
+            config_resource = resource_files("ai_rules") / "config" / "profiles"
+            self._profiles_dir = Path(str(config_resource))
+
+    def list_profiles(self) -> list[str]:
+        """List all available profile names."""
+        if not self._profiles_dir.exists():
+            return ["default"]
+
+        profiles = []
+        for path in self._profiles_dir.glob("*.yaml"):
+            profiles.append(path.stem)
+
+        if "default" not in profiles:
+            profiles.append("default")
+
+        return sorted(profiles)
+
+    def load_profile(self, name: str) -> Profile:
+        """Load a profile by name, resolving inheritance.
+
+        Args:
+            name: Profile name (without .yaml extension)
+
+        Returns:
+            Fully resolved Profile with inherited values merged
+
+        Raises:
+            ProfileNotFoundError: If profile doesn't exist
+            CircularInheritanceError: If circular inheritance detected
+        """
+        return self._load_with_inheritance(name, visited=set())
+
+    def _load_with_inheritance(self, name: str, visited: set[str]) -> Profile:
+        """Recursively load profile with inheritance chain."""
+        if name in visited:
+            cycle = " -> ".join(visited) + f" -> {name}"
+            raise CircularInheritanceError(
+                f"Circular profile inheritance detected: {cycle}"
+            )
+
+        visited.add(name)
+
+        profile_path = self._profiles_dir / f"{name}.yaml"
+
+        if not profile_path.exists():
+            if name == "default":
+                return Profile(
+                    name="default", description="Default profile (no overrides)"
+                )
+            available = self.list_profiles()
+            raise ProfileNotFoundError(
+                f"Profile '{name}' not found. Available profiles: {', '.join(available)}"
+            )
+
+        try:
+            with open(profile_path) as f:
+                data = yaml.safe_load(f) or {}
+        except yaml.YAMLError as e:
+            raise ProfileError(f"Profile '{name}' has invalid YAML: {e}") from e
+
+        self._validate_profile_data(data, name)
+
+        profile = Profile(
+            name=data.get("name", name),
+            description=data.get("description", ""),
+            extends=data.get("extends"),
+            settings_overrides=data.get("settings_overrides", {}),
+            exclude_symlinks=data.get("exclude_symlinks", []),
+            mcp_overrides=data.get("mcp_overrides", {}),
+        )
+
+        if profile.extends:
+            parent = self._load_with_inheritance(profile.extends, visited.copy())
+            profile = self._merge_profiles(parent, profile)
+
+        return profile
+
+    def _validate_profile_data(self, data: dict[str, Any], profile_name: str) -> None:
+        """Validate profile data types."""
+        if "settings_overrides" in data and not isinstance(
+            data["settings_overrides"], dict
+        ):
+            raise ProfileError(
+                f"Profile '{profile_name}': settings_overrides must be a dict"
+            )
+        if "exclude_symlinks" in data and not isinstance(
+            data["exclude_symlinks"], list
+        ):
+            raise ProfileError(
+                f"Profile '{profile_name}': exclude_symlinks must be a list"
+            )
+        if "mcp_overrides" in data and not isinstance(data["mcp_overrides"], dict):
+            raise ProfileError(
+                f"Profile '{profile_name}': mcp_overrides must be a dict"
+            )
+
+    def _merge_profiles(self, parent: Profile, child: Profile) -> Profile:
+        """Merge parent profile into child, with child taking precedence."""
+        merged_settings = deep_merge(
+            parent.settings_overrides, child.settings_overrides
+        )
+
+        merged_mcp = deep_merge(parent.mcp_overrides, child.mcp_overrides)
+
+        merged_excludes = list(
+            set(parent.exclude_symlinks) | set(child.exclude_symlinks)
+        )
+
+        return Profile(
+            name=child.name,
+            description=child.description,
+            extends=child.extends,
+            settings_overrides=merged_settings,
+            exclude_symlinks=merged_excludes,
+            mcp_overrides=merged_mcp,
+        )
+
+    def get_profile_info(self, name: str) -> dict[str, Any]:
+        """Get profile information without resolving inheritance."""
+        profile_path = self._profiles_dir / f"{name}.yaml"
+        if not profile_path.exists():
+            if name == "default":
+                return {
+                    "name": "default",
+                    "description": "Default profile (no overrides)",
+                }
+            raise ProfileNotFoundError(f"Profile '{name}' not found")
+
+        try:
+            with open(profile_path) as f:
+                return yaml.safe_load(f) or {}
+        except yaml.YAMLError as e:
+            raise ProfileError(f"Profile '{name}' has invalid YAML: {e}") from e

ai_rules/state.py

@@ -0,0 +1,47 @@
+"""State management for ai-rules."""
+
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+def _get_state_file() -> Path:
+    """Get the state file path."""
+    return Path.home() / ".ai-rules" / "state.yaml"
+
+
+def get_state() -> dict[str, Any]:
+    """Load state from file."""
+    state_file = _get_state_file()
+    if not state_file.exists():
+        return {}
+
+    try:
+        with state_file.open() as f:
+            return yaml.safe_load(f) or {}
+    except Exception:
+        return {}
+
+
+def _save_state(state: dict[str, Any]) -> None:
+    """Save state to file."""
+    state_file = _get_state_file()
+    state_file.parent.mkdir(parents=True, exist_ok=True)
+    with state_file.open("w") as f:
+        yaml.dump(state, f, default_flow_style=False, sort_keys=False)
+
+
+def get_active_profile() -> str | None:
+    """Get the currently active profile."""
+    state = get_state()
+    return state.get("active_profile")
+
+
+def set_active_profile(profile: str) -> None:
+    """Set the active profile."""
+    state = get_state()
+    state["active_profile"] = profile
+    state["last_install"] = datetime.now(UTC).isoformat()
+    _save_state(state)

ai_rules/utils.py

@@ -0,0 +1,35 @@
+"""Shared utility functions."""
+
+import copy
+
+from typing import Any
+
+
+def deep_merge(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
+    """Deep merge two dictionaries, with override values taking precedence.
+
+    Supports merging nested dictionaries and arrays. Arrays are merged element-by-element,
+    with dict elements being recursively merged.
+
+    Uses deep copy to prevent mutation of the base dictionary.
+    """
+    result = copy.deepcopy(base)
+    for key, value in override.items():
+        if key not in result:
+            result[key] = value
+        elif isinstance(result[key], dict) and isinstance(value, dict):
+            result[key] = deep_merge(result[key], value)
+        elif isinstance(result[key], list) and isinstance(value, list):
+            merged_array = copy.deepcopy(result[key])
+            for i, item in enumerate(value):
+                if i < len(merged_array):
+                    if isinstance(merged_array[i], dict) and isinstance(item, dict):
+                        merged_array[i] = deep_merge(merged_array[i], item)
+                    else:
+                        merged_array[i] = item
+                else:
+                    merged_array.append(item)
+            result[key] = merged_array
+        else:
+            result[key] = value
+    return result