devsync 0.5.5__py3-none-any.whl

aiconfigkit/core/package_manifest.py

@@ -0,0 +1,248 @@
+"""Package manifest parsing and validation."""
+
+from pathlib import Path
+
+import yaml
+
+from aiconfigkit.core.models import (
+    CommandComponent,
+    CredentialDescriptor,
+    HookComponent,
+    InstructionComponent,
+    MCPServerComponent,
+    Package,
+    PackageComponents,
+    ResourceComponent,
+)
+
+
+class ValidationError(Exception):
+    """Raised when manifest validation fails."""
+
+    pass
+
+
+class PackageManifestParser:
+    """
+    Parser and validator for package manifest files.
+
+    Parses ai-config-kit-package.yaml files and validates their structure
+    and component references.
+    """
+
+    def __init__(self, package_root: Path):
+        """
+        Initialize parser.
+
+        Args:
+            package_root: Root directory of the package
+        """
+        self.package_root = package_root
+        self.manifest_path = package_root / "ai-config-kit-package.yaml"
+
+    def parse(self) -> Package:
+        """
+        Parse package manifest YAML file.
+
+        Returns:
+            Package object with all components
+
+        Raises:
+            FileNotFoundError: If manifest file doesn't exist
+            yaml.YAMLError: If YAML is invalid
+            ValidationError: If manifest structure is invalid
+        """
+        if not self.manifest_path.exists():
+            raise FileNotFoundError(f"Manifest not found: {self.manifest_path}")
+
+        with open(self.manifest_path, "r") as f:
+            data = yaml.safe_load(f)
+
+        if not data:
+            raise ValidationError("Manifest is empty")
+
+        # Extract required fields
+        try:
+            name = data["name"]
+            version = data["version"]
+            description = data["description"]
+            author = data["author"]
+            license_type = data["license"]
+            namespace = data.get("namespace", "local/local")
+        except KeyError as e:
+            raise ValidationError(f"Missing required field: {e}")
+
+        # Parse components
+        components_data = data.get("components", {})
+        # Handle case where components: is specified but empty (parses to None)
+        if components_data is None:
+            components_data = {}
+        components = self._parse_components(components_data)
+
+        # Create package
+        package = Package(
+            name=name,
+            version=version,
+            description=description,
+            author=author,
+            license=license_type,
+            namespace=namespace,
+            components=components,
+        )
+
+        return package
+
+    def _parse_components(self, components_data: dict) -> PackageComponents:
+        """
+        Parse components section of manifest.
+
+        Args:
+            components_data: Components dictionary from manifest
+
+        Returns:
+            PackageComponents object
+        """
+        # Parse instructions
+        instructions = []
+        for inst_data in components_data.get("instructions", []):
+            instructions.append(
+                InstructionComponent(
+                    name=inst_data["name"],
+                    file=inst_data["file"],
+                    description=inst_data["description"],
+                    tags=inst_data.get("tags", []),
+                    ide_support=inst_data.get("ide_support"),
+                )
+            )
+
+        # Parse MCP servers
+        mcp_servers = []
+        for mcp_data in components_data.get("mcp_servers", []):
+            credentials = []
+            for cred_data in mcp_data.get("credentials", []):
+                credentials.append(
+                    CredentialDescriptor(
+                        name=cred_data["name"],
+                        description=cred_data["description"],
+                        required=cred_data.get("required", True),
+                        default=cred_data.get("default"),
+                        example=cred_data.get("example"),
+                    )
+                )
+
+            mcp_servers.append(
+                MCPServerComponent(
+                    name=mcp_data["name"],
+                    file=mcp_data["file"],
+                    description=mcp_data["description"],
+                    credentials=credentials,
+                    ide_support=mcp_data.get("ide_support", ["claude_code", "windsurf"]),
+                )
+            )
+
+        # Parse hooks
+        hooks = []
+        for hook_data in components_data.get("hooks", []):
+            hooks.append(
+                HookComponent(
+                    name=hook_data["name"],
+                    file=hook_data["file"],
+                    description=hook_data["description"],
+                    hook_type=hook_data["hook_type"],
+                    ide_support=hook_data.get("ide_support", ["claude_code"]),
+                )
+            )
+
+        # Parse commands
+        commands = []
+        for cmd_data in components_data.get("commands", []):
+            commands.append(
+                CommandComponent(
+                    name=cmd_data["name"],
+                    file=cmd_data["file"],
+                    description=cmd_data["description"],
+                    command_type=cmd_data["command_type"],
+                    ide_support=cmd_data.get("ide_support", []),
+                )
+            )
+
+        # Parse resources
+        resources = []
+        for res_data in components_data.get("resources", []):
+            resources.append(
+                ResourceComponent(
+                    name=res_data["name"],
+                    file=res_data["file"],
+                    description=res_data["description"],
+                    install_path=res_data.get("install_path", res_data["file"]),  # Default to file path
+                    checksum=res_data["checksum"],
+                    size=res_data["size"],
+                )
+            )
+
+        return PackageComponents(
+            instructions=instructions,
+            mcp_servers=mcp_servers,
+            hooks=hooks,
+            commands=commands,
+            resources=resources,
+        )
+
+    def validate(self, package: Package) -> list[str]:
+        """
+        Validate package manifest completeness and file references.
+
+        Args:
+            package: Package object to validate
+
+        Returns:
+            List of validation error messages (empty if valid)
+        """
+        import re
+
+        errors = []
+
+        # Validate version format (semantic versioning: X.Y.Z)
+        version_pattern = r"^\d+\.\d+\.\d+(-[a-zA-Z0-9.-]+)?(\+[a-zA-Z0-9.-]+)?$"
+        if not re.match(version_pattern, package.version):
+            errors.append(f"Invalid version format: {package.version}. Must follow semantic versioning (X.Y.Z)")
+
+        # Validate all component files exist
+        for instruction in package.components.instructions:
+            file_path = self.package_root / instruction.file
+            if not file_path.exists():
+                errors.append(f"Instruction file not found: {instruction.file}")
+
+        for mcp in package.components.mcp_servers:
+            file_path = self.package_root / mcp.file
+            if not file_path.exists():
+                errors.append(f"MCP config file not found: {mcp.file}")
+
+        for hook in package.components.hooks:
+            file_path = self.package_root / hook.file
+            if not file_path.exists():
+                errors.append(f"Hook file not found: {hook.file}")
+
+        for command in package.components.commands:
+            file_path = self.package_root / command.file
+            if not file_path.exists():
+                errors.append(f"Command file not found: {command.file}")
+
+        for resource in package.components.resources:
+            file_path = self.package_root / resource.file
+            if not file_path.exists():
+                errors.append(f"Resource file not found: {resource.file}")
+
+        # Validate component name uniqueness within each type
+        inst_names = [i.name for i in package.components.instructions]
+        if len(inst_names) != len(set(inst_names)):
+            errors.append("Duplicate instruction names found")
+
+        mcp_names = [m.name for m in package.components.mcp_servers]
+        if len(mcp_names) != len(set(mcp_names)):
+            errors.append("Duplicate MCP server names found")
+
+        # Note: We allow empty packages (for edge case testing)
+        # In practice, most packages should have at least one component
+
+        return errors

aiconfigkit/core/repository.py

@@ -0,0 +1,298 @@
+"""Repository parsing and management."""
+
+import hashlib
+import logging
+from pathlib import Path
+from typing import Optional
+
+import yaml
+
+from aiconfigkit.core.models import (
+    AIToolType,
+    Instruction,
+    InstructionBundle,
+    MCPServer,
+    MCPSet,
+    Repository,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class RepositoryParser:
+    """Parse instruction repository metadata and files."""
+
+    def __init__(self, repo_path: Path):
+        """
+        Initialize repository parser.
+
+        Args:
+            repo_path: Path to cloned repository
+        """
+        self.repo_path = repo_path
+        self.metadata_file = repo_path / "templatekit.yaml"
+
+    def parse(self) -> Repository:
+        """
+        Parse repository and return Repository object.
+
+        Returns:
+            Repository with instructions and bundles loaded
+
+        Raises:
+            FileNotFoundError: If templatekit.yaml not found
+            ValueError: If metadata is invalid
+        """
+        if not self.metadata_file.exists():
+            raise FileNotFoundError(f"Repository metadata file not found: {self.metadata_file}")
+
+        with open(self.metadata_file, "r", encoding="utf-8") as f:
+            metadata = yaml.safe_load(f)
+
+        if not metadata:
+            raise ValueError("Repository metadata file is empty")
+
+        # Parse instructions
+        instructions = []
+        for inst_data in metadata.get("instructions", []):
+            instruction = self._parse_instruction(inst_data)
+            instructions.append(instruction)
+
+        # Parse bundles
+        bundles = []
+        for bundle_data in metadata.get("bundles", []):
+            bundle = self._parse_bundle(bundle_data)
+            bundles.append(bundle)
+
+        # Extract repository-level metadata
+        repo_metadata = {
+            "name": metadata.get("name", ""),
+            "description": metadata.get("description", ""),
+            "version": metadata.get("version", ""),
+        }
+
+        return Repository(
+            url="",  # Will be set by caller
+            instructions=instructions,
+            bundles=bundles,
+            metadata=repo_metadata,
+        )
+
+    def _parse_instruction(self, data: dict) -> Instruction:
+        """Parse instruction from metadata dictionary."""
+        name = data.get("name")
+        if not name:
+            raise ValueError("Instruction missing required 'name' field")
+
+        description = data.get("description", "")
+        file_path = data.get("file", "")
+
+        if not file_path:
+            raise ValueError(f"Instruction '{name}' missing 'file' field")
+
+        # Load instruction content
+        full_path = self.repo_path / file_path
+        if not full_path.exists():
+            raise FileNotFoundError(f"Instruction file not found: {full_path}")
+
+        content = full_path.read_text(encoding="utf-8")
+
+        # Calculate checksum
+        checksum = self._calculate_checksum(content)
+
+        # Parse AI tools
+        ai_tools = []
+        for tool_str in data.get("ai_tools", []):
+            try:
+                ai_tools.append(AIToolType(tool_str.lower()))
+            except ValueError:
+                # Skip unknown AI tool types
+                pass
+
+        return Instruction(
+            name=name,
+            description=description,
+            content=content,
+            file_path=file_path,
+            tags=data.get("tags", []),
+            checksum=checksum,
+            ai_tools=ai_tools,
+        )
+
+    def _parse_bundle(self, data: dict) -> InstructionBundle:
+        """Parse bundle from metadata dictionary."""
+        name = data.get("name")
+        if not name:
+            raise ValueError("Bundle missing required 'name' field")
+
+        description = data.get("description", "")
+        instructions = data.get("instructions", [])
+
+        if not instructions:
+            raise ValueError(f"Bundle '{name}' has no instructions")
+
+        return InstructionBundle(
+            name=name,
+            description=description,
+            instructions=instructions,
+            tags=data.get("tags", []),
+        )
+
+    def _calculate_checksum(self, content: str) -> str:
+        """Calculate SHA-256 checksum of content."""
+        return hashlib.sha256(content.encode("utf-8")).hexdigest()
+
+    def get_instruction_by_name(self, name: str) -> Optional[Instruction]:
+        """
+        Find instruction by name in repository.
+
+        Args:
+            name: Instruction name
+
+        Returns:
+            Instruction if found, None otherwise
+        """
+        repo = self.parse()
+        for instruction in repo.instructions:
+            if instruction.name == name:
+                return instruction
+        return None
+
+    def get_bundle_by_name(self, name: str) -> Optional[InstructionBundle]:
+        """
+        Find bundle by name in repository.
+
+        Args:
+            name: Bundle name
+
+        Returns:
+            Bundle if found, None otherwise
+        """
+        repo = self.parse()
+        for bundle in repo.bundles:
+            if bundle.name == name:
+                return bundle
+        return None
+
+    def get_instructions_for_bundle(self, bundle_name: str) -> list[Instruction]:
+        """
+        Get all instructions for a bundle.
+
+        Args:
+            bundle_name: Name of bundle
+
+        Returns:
+            List of Instruction objects
+
+        Raises:
+            ValueError: If bundle not found or instruction in bundle not found
+        """
+        bundle = self.get_bundle_by_name(bundle_name)
+        if not bundle:
+            raise ValueError(f"Bundle not found: {bundle_name}")
+
+        repo = self.parse()
+        instructions = []
+
+        for inst_name in bundle.instructions:
+            # Find instruction
+            instruction = None
+            for inst in repo.instructions:
+                if inst.name == inst_name:
+                    instruction = inst
+                    break
+
+            if not instruction:
+                raise ValueError(f"Bundle '{bundle_name}' references unknown instruction: {inst_name}")
+
+            instructions.append(instruction)
+
+        return instructions
+
+    def parse_mcp_servers(self, namespace: str) -> list[MCPServer]:
+        """
+        Parse MCP servers from templatekit.yaml (templatekit.yaml).
+
+        Args:
+            namespace: Namespace for these servers
+
+        Returns:
+            List of MCPServer objects
+        """
+        if not self.metadata_file.exists():
+            return []
+
+        with open(self.metadata_file, "r", encoding="utf-8") as f:
+            metadata = yaml.safe_load(f)
+
+        if not metadata:
+            return []
+
+        servers = []
+        for server_data in metadata.get("mcp_servers", []):
+            try:
+                server = MCPServer.from_dict(server_data, namespace)
+                servers.append(server)
+            except Exception as e:
+                logger.warning(f"Failed to parse MCP server {server_data.get('name', 'unknown')}: {e}")
+
+        return servers
+
+    def parse_mcp_sets(self, namespace: str) -> list[MCPSet]:
+        """
+        Parse MCP sets from templatekit.yaml (templatekit.yaml).
+
+        Args:
+            namespace: Namespace for these sets
+
+        Returns:
+            List of MCPSet objects
+        """
+        if not self.metadata_file.exists():
+            return []
+
+        with open(self.metadata_file, "r", encoding="utf-8") as f:
+            metadata = yaml.safe_load(f)
+
+        if not metadata:
+            return []
+
+        sets = []
+        for set_data in metadata.get("mcp_sets", []):
+            try:
+                mcp_set = MCPSet.from_dict(set_data, namespace)
+                sets.append(mcp_set)
+            except Exception as e:
+                logger.warning(f"Failed to parse MCP set {set_data.get('name', 'unknown')}: {e}")
+
+        return sets
+
+
+def validate_repository_structure(repo_path: Path) -> Optional[str]:
+    """
+    Validate repository has correct structure.
+
+    Args:
+        repo_path: Path to repository
+
+    Returns:
+        None if valid, error message if invalid
+    """
+    # Check for metadata file
+    metadata_file = repo_path / "templatekit.yaml"
+    if not metadata_file.exists():
+        return "Missing templatekit.yaml metadata file"
+
+    # Try to parse metadata
+    try:
+        parser = RepositoryParser(repo_path)
+        repo = parser.parse()
+
+        # Validate at least one instruction or bundle
+        if not repo.instructions and not repo.bundles:
+            return "Repository has no instructions or bundles"
+
+    except Exception as e:
+        return f"Invalid repository metadata: {str(e)}"
+
+    return None