agent-notes 2.0.4__py3-none-any.whl

agent_notes/registries/agent_registry.py

@@ -0,0 +1,107 @@
+"""Agent registry for loading and managing agent configurations."""
+
+from __future__ import annotations
+from pathlib import Path
+from typing import Optional
+from functools import lru_cache
+
+from ..config import AGENTS_YAML
+from ..domain.agent import AgentSpec
+from ._base import load_yaml_file
+
+
+class AgentRegistry:
+    """Registry of agent configurations from agents.yaml."""
+    
+    def __init__(self, agents: list[AgentSpec]):
+        self._agents = agents
+        self._by_name = {a.name: a for a in agents}
+    
+    def all(self) -> list[AgentSpec]:
+        """Return all agents."""
+        return self._agents.copy()
+    
+    def get(self, name: str) -> AgentSpec:
+        """Get agent by name. Raises KeyError if unknown."""
+        if name not in self._by_name:
+            raise KeyError(f"Agent '{name}' not found in registry")
+        return self._by_name[name]
+    
+    def names(self) -> list[str]:
+        """Return sorted list of agent names."""
+        return sorted(self._by_name.keys())
+    
+    def with_role(self, role: str) -> list[AgentSpec]:
+        """Return agents with the specified role."""
+        return [a for a in self._agents if a.role == role]
+
+
+def load_agent_registry(yaml_path: Optional[Path] = None) -> AgentRegistry:
+    """Load agents from agents.yaml. Single file, not a directory."""
+    if yaml_path is None:
+        yaml_path = AGENTS_YAML
+    
+    if not yaml_path.exists():
+        raise ValueError(f"Agents file not found: {yaml_path}")
+    
+    data = load_yaml_file(yaml_path)
+    
+    # The YAML has an 'agents' top-level key
+    agents_data = data.get("agents", {})
+    if not agents_data:
+        return AgentRegistry([])
+    
+    # Known top-level keys that are NOT per-backend config
+    NON_BACKEND_KEYS = {"description", "role", "mode", "color", "effort", "claude_exclude"}
+    
+    agents = []
+    for name, config in agents_data.items():
+        # Extract required fields
+        if "description" not in config:
+            raise ValueError(f"Missing 'description' field for agent '{name}' in {yaml_path}")
+        if "role" not in config:
+            raise ValueError(f"Missing 'role' field for agent '{name}' in {yaml_path}")
+        if "mode" not in config:
+            raise ValueError(f"Missing 'mode' field for agent '{name}' in {yaml_path}")
+        
+        # Everything that is NOT in NON_BACKEND_KEYS is treated as per-backend config.
+        # This is what makes the loader registry-driven: adding a new CLI named
+        # "gemini" just means agents.yaml may have a 'gemini:' key and it flows
+        # through automatically.
+        backends: dict[str, dict] = {}
+        for key, value in config.items():
+            if key in NON_BACKEND_KEYS:
+                continue
+            if isinstance(value, dict):
+                backends[key] = value
+            else:
+                # Non-dict top-level keys are unknown; ignore with no error to be
+                # lenient with user-edited YAML (could log a warning later).
+                pass
+
+        # Backward compat: translate legacy top-level claude_exclude into backends
+        # Note: This is the only hardcoded "claude" reference for backward compatibility
+        if config.get("claude_exclude"):
+            backends.setdefault("claude", {})["exclude"] = True
+
+        agent = AgentSpec(
+            name=name,
+            description=config["description"],
+            role=config["role"],
+            mode=config["mode"],
+            color=config.get("color"),
+            effort=config.get("effort"),
+            backends=backends,
+        )
+        agents.append(agent)
+    
+    # Sort by name for deterministic order
+    agents.sort(key=lambda a: a.name)
+    
+    return AgentRegistry(agents)
+
+
+@lru_cache(maxsize=1)
+def default_agent_registry() -> AgentRegistry:
+    """Return the default agent registry, cached."""
+    return load_agent_registry()

agent_notes/registries/cli_registry.py

@@ -0,0 +1,89 @@
+"""CLI backend registry for loading and managing CLI descriptors."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+from functools import lru_cache
+
+from ..config import DATA_DIR
+from ..domain.cli_backend import CLIBackend
+from ._base import load_yaml_dir, require_fields
+
+
+class CLIRegistry:
+    """Registry of all loaded CLI backends."""
+    
+    def __init__(self, backends: list[CLIBackend]):
+        self._backends = backends
+        self._by_name = {b.name: b for b in backends}
+    
+    def all(self) -> list[CLIBackend]:
+        """Return all backends."""
+        return self._backends.copy()
+    
+    def get(self, name: str) -> CLIBackend:
+        """Get backend by name. Raises KeyError if unknown."""
+        return self._by_name[name]
+    
+    def names(self) -> list[str]:
+        """Return sorted list of backend names."""
+        return sorted(self._by_name.keys())
+    
+    def with_feature(self, feature: str) -> list[CLIBackend]:
+        """Return backends where self.supports(feature) is True."""
+        return [b for b in self._backends if b.supports(feature)]
+
+
+def load_registry(cli_dir: Optional[Path] = None) -> CLIRegistry:
+    """Load all *.yaml files from cli_dir (default: agent_notes/data/cli/)
+    and return a CLIRegistry. Raises ValueError if directory missing or any YAML invalid.
+    """
+    if cli_dir is None:
+        cli_dir = DATA_DIR / "cli"
+    
+    if not cli_dir.exists():
+        raise ValueError(f"CLI directory not found: {cli_dir}")
+    
+    required_fields = ["name", "label", "global_home", "layout", "features"]
+    try:
+        items = load_yaml_dir(cli_dir, required_fields)
+    except ValueError as e:
+        # Maintain backward compatibility for error messages
+        if "Registry directory not found" in str(e):
+            raise ValueError(f"CLI directory not found: {cli_dir}")
+        raise
+    
+    backends = []
+    for yaml_file, data in items:
+        # Expand global_home path
+        global_home = Path(data["global_home"]).expanduser()
+        
+        backend = CLIBackend(
+            name=data["name"],
+            label=data["label"],
+            global_home=global_home,
+            local_dir=data["local_dir"],
+            layout=data["layout"],
+            features=data["features"],
+            global_template=data.get("global_template"),
+            exclude_flag=data.get("exclude_flag"),
+            strip_memory_section=data.get("strip_memory_section", False),
+            settings_template=data.get("settings_template"),
+            accepted_providers=tuple(data.get("accepted_providers", []))
+        )
+        backends.append(backend)
+    
+    if not backends:
+        raise ValueError(f"No CLI backends found in {cli_dir}")
+    
+    # Sort by name for deterministic order
+    backends.sort(key=lambda b: b.name)
+    
+    return CLIRegistry(backends)
+
+
+@lru_cache(maxsize=1)
+def default_registry() -> CLIRegistry:
+    """Return the default CLI registry, cached."""
+    return load_registry()

agent_notes/registries/model_registry.py

@@ -0,0 +1,85 @@
+"""Model registry for loading and managing model descriptors."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+from functools import lru_cache
+
+from ..config import DATA_DIR
+from ..domain.model import Model
+from ._base import load_yaml_file, require_fields
+
+
+class ModelRegistry:
+    def __init__(self, models: list[Model]):
+        self._by_id: dict[str, Model] = {m.id: m for m in models}
+
+    def all(self) -> list[Model]:
+        return sorted(self._by_id.values(), key=lambda m: m.id)
+
+    def get(self, model_id: str) -> Model:
+        if model_id not in self._by_id:
+            raise KeyError(f"Model '{model_id}' not found in registry")
+        return self._by_id[model_id]
+
+    def ids(self) -> list[str]:
+        return sorted(self._by_id.keys())
+
+    def by_class(self, class_name: str) -> list[Model]:
+        """All models with model_class == class_name, sorted by id."""
+        return sorted(
+            [m for m in self._by_id.values() if m.model_class == class_name],
+            key=lambda m: m.id,
+        )
+
+    def compatible_with_providers(self, providers: list[str]) -> list[Model]:
+        """Return models that have at least one alias matching providers list.
+        Useful for CLI filtering: pass cli.accepted_providers."""
+        result = []
+        for m in self._by_id.values():
+            if any(p in m.aliases for p in providers):
+                result.append(m)
+        return sorted(result, key=lambda m: m.id)
+
+
+def load_model_registry(models_dir: Optional[Path] = None) -> ModelRegistry:
+    """Load all *.yaml files from models_dir (default: data/models/)."""
+    if models_dir is None:
+        models_dir = DATA_DIR / "models"
+    
+    if not models_dir.is_dir():
+        raise ValueError(f"Models directory not found: {models_dir}")
+    
+    models: list[Model] = []
+    for yaml_file in sorted(models_dir.glob("*.yaml")):
+        try:
+            data = load_yaml_file(yaml_file)
+        except ValueError as e:
+            # Maintain backward compatibility for error messages  
+            if "Invalid YAML" in str(e):
+                raise ValueError(f"Invalid YAML in {yaml_file.name}: {str(e).split(': ', 1)[1]}")
+            raise
+        
+        require_fields(
+            data, ["id", "label", "family", "class", "aliases"], yaml_file,
+            msg_template="Missing field '{field}' in {filename}",
+        )
+        
+        models.append(Model(
+            id=data["id"],
+            label=data["label"],
+            family=data["family"],
+            model_class=data["class"],
+            aliases=data["aliases"],
+            pricing=data.get("pricing", {}) or {},
+            capabilities=data.get("capabilities", {}) or {},
+        ))
+    
+    return ModelRegistry(models)
+
+
+@lru_cache(maxsize=1)
+def default_model_registry() -> ModelRegistry:
+    """Cached singleton."""
+    return load_model_registry()

agent_notes/registries/role_registry.py

@@ -0,0 +1,64 @@
+"""Role registry for loading and managing role descriptors."""
+
+from __future__ import annotations
+from pathlib import Path
+from typing import Optional
+from functools import lru_cache
+
+from ..config import DATA_DIR
+from ..domain.role import Role
+from ._base import load_yaml_file, require_fields
+
+
+class RoleRegistry:
+    def __init__(self, roles: list[Role]):
+        self._by_name: dict[str, Role] = {r.name: r for r in roles}
+
+    def all(self) -> list[Role]:
+        return sorted(self._by_name.values(), key=lambda r: r.name)
+
+    def get(self, name: str) -> Role:
+        if name not in self._by_name:
+            raise KeyError(f"Role '{name}' not found in registry")
+        return self._by_name[name]
+
+    def names(self) -> list[str]:
+        return sorted(self._by_name.keys())
+
+
+def load_role_registry(roles_dir: Optional[Path] = None) -> RoleRegistry:
+    if roles_dir is None:
+        roles_dir = DATA_DIR / "roles"
+    
+    if not roles_dir.is_dir():
+        raise ValueError(f"Roles directory not found: {roles_dir}")
+    
+    roles: list[Role] = []
+    for yaml_file in sorted(roles_dir.glob("*.yaml")):
+        try:
+            data = load_yaml_file(yaml_file)
+        except ValueError as e:
+            # Maintain backward compatibility for error messages
+            if "Invalid YAML" in str(e):
+                raise ValueError(f"Invalid YAML in {yaml_file.name}: {str(e).split(': ', 1)[1]}")
+            raise
+        
+        require_fields(
+            data, ["name", "label", "description", "typical_class"], yaml_file,
+            msg_template="Missing field '{field}' in {filename}",
+        )
+        
+        roles.append(Role(
+            name=data["name"],
+            label=data["label"],
+            description=data["description"],
+            typical_class=data["typical_class"],
+            color=data.get("color", ""),
+        ))
+    
+    return RoleRegistry(roles)
+
+
+@lru_cache(maxsize=1)
+def default_role_registry() -> RoleRegistry:
+    return load_role_registry()

agent_notes/registries/rule_registry.py

@@ -0,0 +1,80 @@
+"""Rule registry for loading and managing rule descriptors."""
+
+from __future__ import annotations
+from pathlib import Path
+from typing import Optional
+from functools import lru_cache
+
+from ..config import RULES_DIR
+from ..domain.rule import Rule
+
+
+class RuleRegistry:
+    """Registry of rule descriptors from data/rules/*.md."""
+    
+    def __init__(self, rules: list[Rule]):
+        self._rules = rules
+        self._by_name = {r.name: r for r in rules}
+    
+    def all(self) -> list[Rule]:
+        """Return all rules."""
+        return self._rules.copy()
+    
+    def get(self, name: str) -> Rule:
+        """Get rule by name. Raises KeyError if unknown."""
+        if name not in self._by_name:
+            raise KeyError(f"Rule '{name}' not found in registry")
+        return self._by_name[name]
+    
+    def names(self) -> list[str]:
+        """Return sorted list of rule names."""
+        return sorted(self._by_name.keys())
+
+
+def _extract_title_from_md(md_path: Path) -> str:
+    """Extract first # heading from markdown file, or return filename stem."""
+    if not md_path.exists():
+        return md_path.stem
+    
+    try:
+        content = md_path.read_text()
+        lines = content.split('\n')
+        
+        for line in lines:
+            line = line.strip()
+            if line.startswith('# '):
+                return line[2:].strip()
+        
+        # No heading found, use filename
+        return md_path.stem
+    except Exception:
+        # Fallback to filename if we can't read the file
+        return md_path.stem
+
+
+def load_rule_registry(rules_dir: Optional[Path] = None) -> RuleRegistry:
+    """Load all rules from data/rules/*.md."""
+    if rules_dir is None:
+        rules_dir = RULES_DIR
+    
+    if not rules_dir.exists():
+        return RuleRegistry([])
+    
+    rules = []
+    for rule_file in sorted(rules_dir.glob("*.md")):
+        title = _extract_title_from_md(rule_file)
+        
+        rule = Rule(
+            name=rule_file.stem,
+            path=rule_file,
+            title=title
+        )
+        rules.append(rule)
+    
+    return RuleRegistry(rules)
+
+
+@lru_cache(maxsize=1)
+def default_rule_registry() -> RuleRegistry:
+    """Return the default rule registry, cached."""
+    return load_rule_registry()

agent_notes/registries/skill_registry.py

@@ -0,0 +1,141 @@
+"""Skill registry for loading and managing skill descriptors."""
+
+from __future__ import annotations
+from pathlib import Path
+from typing import Optional, Dict, List
+from functools import lru_cache
+import re
+
+from ..config import SKILLS_DIR
+from ..domain.skill import Skill
+
+
+class SkillRegistry:
+    """Registry of skill descriptors from data/skills/*/SKILL.md."""
+    
+    def __init__(self, skills: list[Skill]):
+        self._skills = skills
+        self._by_name = {s.name: s for s in skills}
+    
+    def all(self) -> list[Skill]:
+        """Return all skills."""
+        return self._skills.copy()
+    
+    def get(self, name: str) -> Skill:
+        """Get skill by name. Raises KeyError if unknown."""
+        if name not in self._by_name:
+            raise KeyError(f"Skill '{name}' not found in registry")
+        return self._by_name[name]
+    
+    def names(self) -> list[str]:
+        """Return sorted list of skill names."""
+        return sorted(self._by_name.keys())
+    
+    def by_group(self) -> Dict[str, List[Skill]]:
+        """Return skills grouped by their group field."""
+        groups: Dict[str, List[Skill]] = {}
+        for skill in self._skills:
+            group_name = skill.group or "uncategorized"
+            if group_name not in groups:
+                groups[group_name] = []
+            groups[group_name].append(skill)
+        
+        # Sort skills within each group
+        for skills_in_group in groups.values():
+            skills_in_group.sort(key=lambda s: s.name)
+        
+        return groups
+
+
+def _parse_skill_frontmatter(skill_md_path: Path) -> tuple[str, Optional[str]]:
+    """Parse SKILL.md frontmatter for description and group.
+    
+    Returns:
+        (description, group) where description is first line if no frontmatter,
+        and group is None if not specified.
+    """
+    if not skill_md_path.exists():
+        return skill_md_path.parent.name, None
+    
+    content = skill_md_path.read_text()
+    lines = content.split('\n')
+    
+    # Check for YAML frontmatter
+    if lines and lines[0].strip() == '---':
+        # Find the closing ---
+        end_idx = None
+        for i in range(1, len(lines)):
+            if lines[i].strip() == '---':
+                end_idx = i
+                break
+        
+        if end_idx is not None:
+            # Parse the YAML frontmatter
+            frontmatter_lines = lines[1:end_idx]
+            group = None
+            description = None
+            
+            for line in frontmatter_lines:
+                if ':' in line:
+                    key, value = line.split(':', 1)
+                    key = key.strip()
+                    value = value.strip().strip('"\'')
+                    if key == 'group':
+                        group = value
+                    elif key == 'description':
+                        description = value
+            
+            # If no description in frontmatter, use first non-empty line after frontmatter
+            if not description:
+                for line in lines[end_idx + 1:]:
+                    line = line.strip()
+                    if line and not line.startswith('#'):
+                        description = line
+                        break
+            
+            return description or skill_md_path.parent.name, group
+    
+    # No frontmatter - use first non-empty line as description
+    for line in lines:
+        line = line.strip()
+        if line:
+            return line, None
+    
+    # Fallback to directory name
+    return skill_md_path.parent.name, None
+
+
+def load_skill_registry(skills_dir: Optional[Path] = None) -> SkillRegistry:
+    """Load all skills from data/skills/*/SKILL.md."""
+    if skills_dir is None:
+        skills_dir = SKILLS_DIR
+    
+    if not skills_dir.exists():
+        return SkillRegistry([])
+    
+    skills = []
+    for skill_dir in sorted(skills_dir.iterdir()):
+        if not skill_dir.is_dir():
+            continue
+        
+        skill_md = skill_dir / "SKILL.md"
+        if not skill_md.exists():
+            continue
+        
+        description, group = _parse_skill_frontmatter(skill_md)
+        
+        skill = Skill(
+            name=skill_dir.name,
+            path=skill_dir,
+            description=description,
+            group=group
+        )
+        skills.append(skill)
+    
+    return SkillRegistry(skills)
+
+
+@lru_cache(maxsize=1)
+def default_skill_registry() -> SkillRegistry:
+    """Return the default skill registry, cached."""
+    return load_skill_registry()

agent_notes/services/__init__.py

@@ -0,0 +1,8 @@
+"""Services — side-effecting operations called by commands."""
+# Re-export commonly used symbols for convenience. Be conservative to avoid namespace pollution.
+from . import fs, ui, state_store, install_state_builder, rendering, diff, diagnostics, validation
+
+# Note: installer causes circular import with cli_backend -> registries -> config -> ui
+# Import installer directly when needed: from agent_notes.services import installer
+
+__all__ = ["fs", "ui", "state_store", "install_state_builder", "rendering", "diff", "diagnostics", "validation"]

agent_notes/services/diagnostics/__init__.py

@@ -0,0 +1,47 @@
+"""Diagnostic checks and fixes for agent-notes installation."""
+
+from ._checks import (
+    check_stale_files,
+    check_broken_symlinks,
+    check_shadowed_files,
+    check_missing_files,
+    check_content_drift,
+    check_build_freshness,
+    _find_dist_source,
+)
+from ._display import (
+    count_stale,
+    _print_status,
+    print_summary,
+    print_issues,
+    _cli_base_dir,
+    _count_agents,
+    _count_skills,
+    _count_scripts,
+    _count_rules,
+    _check_config,
+    _check_role_models,
+)
+from ._fix import do_fix
+
+__all__ = [
+    "check_stale_files",
+    "check_broken_symlinks",
+    "check_shadowed_files",
+    "check_missing_files",
+    "check_content_drift",
+    "check_build_freshness",
+    "_find_dist_source",
+    "count_stale",
+    "_print_status",
+    "print_summary",
+    "print_issues",
+    "_cli_base_dir",
+    "_count_agents",
+    "_count_skills",
+    "_count_scripts",
+    "_count_rules",
+    "_check_config",
+    "_check_role_models",
+    "do_fix",
+]