attune-ai 2.0.0__py3-none-any.whl

attune_llm/commands/loader.py

@@ -0,0 +1,301 @@
+"""Command Loader
+
+Loads commands from directory structures.
+
+Architectural patterns inspired by everything-claude-code by Affaan Mustafa.
+See: https://github.com/affaan-m/everything-claude-code (MIT License)
+See: ACKNOWLEDGMENTS.md for full attribution.
+
+Copyright 2025 Smart AI Memory, LLC
+Licensed under Fair Source 0.9
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Iterator
+from pathlib import Path
+
+from attune_llm.commands.models import CommandConfig
+from attune_llm.commands.parser import CommandParser
+
+logger = logging.getLogger(__name__)
+
+# Default commands directory relative to project root
+DEFAULT_COMMANDS_DIR = ".claude/commands"
+
+# Files to skip when scanning
+SKIP_FILES = frozenset(
+    {
+        "README.md",
+        "readme.md",
+        "CHANGELOG.md",
+        "changelog.md",
+        "INDEX.md",
+        "index.md",
+    }
+)
+
+
+class CommandLoader:
+    """Loader for discovering and loading command markdown files.
+
+    Scans directories for .md files with command definitions and loads
+    them into CommandConfig instances.
+
+    Example:
+        loader = CommandLoader()
+
+        # Load a single command
+        config = loader.load(".claude/commands/commit.md")
+
+        # Load all commands from a directory
+        commands = loader.load_directory(".claude/commands/")
+
+        # Discover and iterate commands lazily
+        for config in loader.discover(".claude/commands/"):
+            print(config.name)
+    """
+
+    def __init__(self, parser: CommandParser | None = None):
+        """Initialize the loader.
+
+        Args:
+            parser: Optional custom parser instance
+
+        """
+        self.parser = parser or CommandParser()
+
+    def load(self, file_path: str | Path) -> CommandConfig:
+        """Load a single command file.
+
+        Args:
+            file_path: Path to the command markdown file
+
+        Returns:
+            CommandConfig instance
+
+        """
+        return self.parser.parse_file(file_path)
+
+    def load_directory(
+        self,
+        directory: str | Path,
+        recursive: bool = False,
+    ) -> dict[str, CommandConfig]:
+        """Load all commands from a directory.
+
+        Args:
+            directory: Directory to scan for .md files
+            recursive: If True, scan subdirectories
+
+        Returns:
+            Dictionary mapping command names to configs
+
+        """
+        commands: dict[str, CommandConfig] = {}
+
+        for config in self.discover(directory, recursive=recursive):
+            if config.name in commands:
+                logger.warning(
+                    "Duplicate command name '%s' - keeping first occurrence",
+                    config.name,
+                )
+                continue
+            commands[config.name] = config
+
+        logger.info("Loaded %d command(s) from %s", len(commands), directory)
+        return commands
+
+    def discover(
+        self,
+        directory: str | Path,
+        recursive: bool = False,
+    ) -> Iterator[CommandConfig]:
+        """Discover and yield commands from a directory.
+
+        Args:
+            directory: Directory to scan
+            recursive: If True, scan subdirectories
+
+        Yields:
+            CommandConfig instances
+
+        """
+        directory = Path(directory)
+
+        if not directory.exists():
+            logger.warning("Commands directory not found: %s", directory)
+            return
+
+        if not directory.is_dir():
+            raise ValueError(f"Not a directory: {directory}")
+
+        # Get pattern for globbing
+        pattern = "**/*.md" if recursive else "*.md"
+
+        for file_path in sorted(directory.glob(pattern)):
+            if not file_path.is_file():
+                continue
+
+            # Skip non-command files
+            if file_path.name in SKIP_FILES:
+                continue
+            if file_path.name.startswith("_"):
+                continue
+            if file_path.name.startswith("."):
+                continue
+
+            try:
+                config = self.parser.parse_file(file_path)
+                yield config
+            except ValueError as e:
+                logger.warning("Skipping invalid command file %s: %s", file_path, e)
+            except FileNotFoundError as e:
+                logger.warning("Command file not found %s: %s", file_path, e)
+            except OSError as e:
+                logger.error("Error loading command file %s: %s", file_path, e)
+
+    def validate_directory(
+        self,
+        directory: str | Path,
+        recursive: bool = False,
+    ) -> dict[str, list[str]]:
+        """Validate all command files in a directory.
+
+        Args:
+            directory: Directory to validate
+            recursive: If True, scan subdirectories
+
+        Returns:
+            Dictionary mapping file paths to lists of errors
+
+        """
+        directory = Path(directory)
+        results: dict[str, list[str]] = {}
+
+        if not directory.exists():
+            return {str(directory): ["Directory not found"]}
+
+        pattern = "**/*.md" if recursive else "*.md"
+
+        for file_path in sorted(directory.glob(pattern)):
+            if not file_path.is_file():
+                continue
+            if file_path.name in SKIP_FILES:
+                continue
+            if file_path.name.startswith("_"):
+                continue
+
+            errors = self.parser.validate_file(file_path)
+            if errors:
+                results[str(file_path)] = errors
+
+        return results
+
+    def get_command_names(
+        self,
+        directory: str | Path,
+        recursive: bool = False,
+    ) -> list[str]:
+        """Get list of command names in a directory without fully loading.
+
+        Args:
+            directory: Directory to scan
+            recursive: If True, scan subdirectories
+
+        Returns:
+            List of command names
+
+        """
+        names: list[str] = []
+        for config in self.discover(directory, recursive=recursive):
+            names.append(config.name)
+        return names
+
+    def find_command_file(
+        self,
+        name: str,
+        directory: str | Path,
+    ) -> Path | None:
+        """Find a command file by name.
+
+        Args:
+            name: Command name to find
+            directory: Directory to search
+
+        Returns:
+            Path to command file or None
+
+        """
+        directory = Path(directory)
+
+        # Try exact match first
+        exact_path = directory / f"{name}.md"
+        if exact_path.exists():
+            return exact_path
+
+        # Search through files
+        for file_path in directory.glob("*.md"):
+            if file_path.stem == name:
+                return file_path
+
+        return None
+
+
+def load_commands_from_paths(
+    paths: list[str | Path],
+    parser: CommandParser | None = None,
+) -> dict[str, CommandConfig]:
+    """Load commands from multiple paths (files or directories).
+
+    Args:
+        paths: List of file or directory paths
+        parser: Optional custom parser
+
+    Returns:
+        Dictionary mapping command names to configs
+
+    """
+    loader = CommandLoader(parser=parser)
+    commands: dict[str, CommandConfig] = {}
+
+    for path in paths:
+        path = Path(path)
+
+        if path.is_file():
+            config = loader.load(path)
+            commands[config.name] = config
+        elif path.is_dir():
+            dir_commands = loader.load_directory(path)
+            commands.update(dir_commands)
+        else:
+            logger.warning("Path not found: %s", path)
+
+    return commands
+
+
+def get_default_commands_directory() -> Path:
+    """Get the default commands directory.
+
+    Searches for .claude/commands/ starting from current directory
+    and walking up to find project root.
+
+    Returns:
+        Path to commands directory
+
+    """
+    current = Path.cwd()
+
+    # Walk up looking for .claude/commands/
+    for parent in [current, *current.parents]:
+        commands_dir = parent / DEFAULT_COMMANDS_DIR
+        if commands_dir.exists():
+            return commands_dir
+
+        # Also check for .claude directory as project root indicator
+        if (parent / ".claude").exists():
+            return commands_dir
+
+    # Fall back to current directory
+    return current / DEFAULT_COMMANDS_DIR

attune_llm/commands/models.py

@@ -0,0 +1,231 @@
+"""Command Configuration Models
+
+Data models for command definitions loaded from markdown files.
+
+Architectural patterns inspired by everything-claude-code by Affaan Mustafa.
+See: https://github.com/affaan-m/everything-claude-code (MIT License)
+See: ACKNOWLEDGMENTS.md for full attribution.
+
+Copyright 2025 Smart AI Memory, LLC
+Licensed under Fair Source 0.9
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+
+class CommandCategory(str, Enum):
+    """Categories for commands."""
+
+    WORKFLOW = "workflow"  # Multi-step workflows
+    GIT = "git"  # Git operations
+    TEST = "test"  # Testing related
+    DOCS = "docs"  # Documentation
+    SECURITY = "security"  # Security analysis
+    PERFORMANCE = "performance"  # Performance tools
+    LEARNING = "learning"  # Pattern learning
+    CONTEXT = "context"  # Context management
+    UTILITY = "utility"  # General utilities
+
+
+@dataclass
+class CommandMetadata:
+    """Metadata for a command extracted from YAML frontmatter.
+
+    Example frontmatter:
+        ---
+        name: compact
+        description: Strategic context compaction
+        category: context
+        aliases: [comp, save-state]
+        hooks:
+          pre: PreCompact
+          post: PostCompact
+        requires_user_id: true
+        ---
+    """
+
+    name: str
+    description: str = ""
+    category: CommandCategory = CommandCategory.UTILITY
+    aliases: list[str] = field(default_factory=list)
+    hooks: dict[str, str] = field(default_factory=dict)
+    requires_user_id: bool = False
+    requires_context: bool = False
+    tags: list[str] = field(default_factory=list)
+    author: str = ""
+    version: str = "1.0"
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary."""
+        return {
+            "name": self.name,
+            "description": self.description,
+            "category": self.category.value,
+            "aliases": self.aliases,
+            "hooks": self.hooks,
+            "requires_user_id": self.requires_user_id,
+            "requires_context": self.requires_context,
+            "tags": self.tags,
+            "author": self.author,
+            "version": self.version,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> CommandMetadata:
+        """Create from dictionary."""
+        category_str = data.get("category", "utility")
+        try:
+            category = CommandCategory(category_str)
+        except ValueError:
+            category = CommandCategory.UTILITY
+
+        return cls(
+            name=data.get("name", ""),
+            description=data.get("description", ""),
+            category=category,
+            aliases=data.get("aliases", []),
+            hooks=data.get("hooks", {}),
+            requires_user_id=data.get("requires_user_id", False),
+            requires_context=data.get("requires_context", False),
+            tags=data.get("tags", []),
+            author=data.get("author", ""),
+            version=data.get("version", "1.0"),
+        )
+
+
+@dataclass
+class CommandConfig:
+    """Complete configuration for a command.
+
+    Combines metadata from YAML frontmatter with the markdown body
+    that contains the command instructions.
+    """
+
+    name: str
+    description: str
+    body: str  # Markdown content with instructions
+    metadata: CommandMetadata
+    source_file: Path | None = None
+    loaded_at: datetime = field(default_factory=datetime.now)
+
+    @property
+    def aliases(self) -> list[str]:
+        """Get command aliases."""
+        return self.metadata.aliases
+
+    @property
+    def category(self) -> CommandCategory:
+        """Get command category."""
+        return self.metadata.category
+
+    @property
+    def hooks(self) -> dict[str, str]:
+        """Get hook configuration."""
+        return self.metadata.hooks
+
+    def get_all_names(self) -> list[str]:
+        """Get command name and all aliases."""
+        return [self.name] + self.aliases
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary."""
+        return {
+            "name": self.name,
+            "description": self.description,
+            "body": self.body,
+            "metadata": self.metadata.to_dict(),
+            "source_file": str(self.source_file) if self.source_file else None,
+            "loaded_at": self.loaded_at.isoformat(),
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> CommandConfig:
+        """Create from dictionary."""
+        return cls(
+            name=data["name"],
+            description=data.get("description", ""),
+            body=data.get("body", ""),
+            metadata=CommandMetadata.from_dict(data.get("metadata", {})),
+            source_file=Path(data["source_file"]) if data.get("source_file") else None,
+            loaded_at=datetime.fromisoformat(data["loaded_at"])
+            if "loaded_at" in data
+            else datetime.now(),
+        )
+
+    def format_for_display(self) -> str:
+        """Format command for display in help."""
+        aliases_str = ""
+        if self.aliases:
+            aliases_str = f" (aliases: {', '.join(self.aliases)})"
+
+        return f"/{self.name}{aliases_str} - {self.description}"
+
+    def format_full_help(self) -> str:
+        """Format full help including body."""
+        lines = [
+            f"# /{self.name}",
+            "",
+            self.description,
+            "",
+        ]
+
+        if self.aliases:
+            lines.extend(
+                [
+                    "## Aliases",
+                    ", ".join(f"/{a}" for a in self.aliases),
+                    "",
+                ]
+            )
+
+        if self.metadata.tags:
+            lines.extend(
+                [
+                    "## Tags",
+                    ", ".join(self.metadata.tags),
+                    "",
+                ]
+            )
+
+        lines.extend(
+            [
+                "## Instructions",
+                "",
+                self.body,
+            ]
+        )
+
+        return "\n".join(lines)
+
+
+@dataclass
+class CommandResult:
+    """Result from executing a command."""
+
+    command_name: str
+    success: bool
+    output: str = ""
+    error: str | None = None
+    duration_ms: float = 0.0
+    hooks_fired: list[str] = field(default_factory=list)
+    context_saved: bool = False
+    patterns_applied: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary."""
+        return {
+            "command_name": self.command_name,
+            "success": self.success,
+            "output": self.output,
+            "error": self.error,
+            "duration_ms": self.duration_ms,
+            "hooks_fired": self.hooks_fired,
+            "context_saved": self.context_saved,
+            "patterns_applied": self.patterns_applied,
+        }