devsync 0.5.5__py3-none-any.whl

aiconfigkit/storage/library.py

@@ -0,0 +1,429 @@
+"""Library management for downloaded instructions."""
+
+import json
+import shutil
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+from aiconfigkit.core.models import LibraryInstruction, LibraryRepository
+from aiconfigkit.utils.paths import get_library_dir
+
+
+class LibraryManager:
+    """
+    Manages the local library of downloaded instructions.
+
+    The library structure:
+    ~/.instructionkit/
+    ├── library/
+    │   ├── repo-namespace-1/
+    │   │   └── instructions/
+    │   │       └── instruction.md
+    │   └── repo-namespace-2/
+    │       └── instructions/
+    └── library.json  (index of all repositories)
+    """
+
+    def __init__(self, library_dir: Optional[Path] = None):
+        """
+        Initialize library manager.
+
+        Args:
+            library_dir: Path to library directory (default: ~/.instructionkit/library)
+        """
+        self.library_dir = library_dir or get_library_dir()
+        self.library_dir.mkdir(parents=True, exist_ok=True)
+
+        self.index_file = self.library_dir.parent / "library.json"
+
+    def get_repo_namespace(self, url: str, repo_name: str) -> str:
+        """
+        Generate a unique namespace for a repository.
+
+        Args:
+            url: Repository URL
+            repo_name: Repository name
+
+        Returns:
+            Namespace string (e.g., 'github.com_company_instructions')
+        """
+        # Parse URL to extract host and path
+        # For local paths, use the folder name
+        if url.startswith(("http://", "https://", "git@")):
+            # Extract domain and repo path
+            # https://github.com/company/instructions -> github.com_company_instructions
+            import re
+
+            # Remove protocol
+            clean_url = re.sub(r"^(https?://|git@)", "", url)
+            # Remove .git suffix
+            clean_url = re.sub(r"\.git$", "", clean_url)
+            # Replace special chars with underscore
+            namespace = re.sub(r"[^a-zA-Z0-9]", "_", clean_url)
+        else:
+            # Local path - use folder name + sanitized path
+            path = Path(url).resolve()
+            namespace = f"local_{path.name}_{abs(hash(str(path))) % 100000}"
+
+        return namespace
+
+    def generate_alias(self, url: str, repo_name: str) -> str:
+        """
+        Auto-generate a friendly alias from URL or repo name.
+
+        Args:
+            url: Repository URL
+            repo_name: Repository name
+
+        Returns:
+            Friendly alias (e.g., 'company-instructions' from github.com/company/instructions)
+        """
+        import re
+
+        if url.startswith(("http://", "https://")):
+            # Extract repo path from URL
+            # https://github.com/company/instructions -> company-instructions
+            match = re.search(r"/([^/]+)/([^/]+?)(?:\.git)?$", url)
+            if match:
+                org, repo = match.groups()
+                return f"{org}-{repo}".lower()
+
+        # Fallback to sanitized repo name
+        return re.sub(r"[^a-z0-9-]", "-", repo_name.lower()).strip("-")
+
+    def load_index(self) -> dict[str, LibraryRepository]:
+        """
+        Load the library index.
+
+        Returns:
+            Dictionary mapping namespace to LibraryRepository
+        """
+        if not self.index_file.exists():
+            return {}
+
+        with open(self.index_file, "r", encoding="utf-8") as f:
+            data = json.load(f)
+
+        return {namespace: LibraryRepository.from_dict(repo_data) for namespace, repo_data in data.items()}
+
+    def save_index(self, repositories: dict[str, LibraryRepository]) -> None:
+        """
+        Save the library index.
+
+        Args:
+            repositories: Dictionary mapping namespace to LibraryRepository
+        """
+        data = {namespace: repo.to_dict() for namespace, repo in repositories.items()}
+
+        with open(self.index_file, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2, ensure_ascii=False)
+
+    def add_repository(
+        self,
+        repo_name: str,
+        repo_description: str,
+        repo_url: str,
+        repo_author: str,
+        repo_version: str,
+        instructions: list[LibraryInstruction],
+        alias: Optional[str] = None,
+        namespace: Optional[str] = None,
+    ) -> LibraryRepository:
+        """
+        Add a repository to the library.
+
+        Args:
+            repo_name: Repository display name
+            repo_description: Repository description
+            repo_url: Repository URL
+            repo_author: Repository author
+            repo_version: Repository version
+            instructions: List of instructions to add
+            alias: User-friendly alias (auto-generated if not provided)
+            namespace: Repository namespace (auto-generated if not provided)
+
+        Returns:
+            Created LibraryRepository
+        """
+        # Generate namespace if not provided
+        if namespace is None:
+            namespace = self.get_repo_namespace(repo_url, repo_name)
+
+        # Auto-generate alias if not provided
+        if alias is None:
+            alias = self.generate_alias(repo_url, repo_name)
+
+        # Create repository directory
+        repo_dir = self.library_dir / namespace
+        repo_dir.mkdir(parents=True, exist_ok=True)
+
+        # Create instructions directory
+        instructions_dir = repo_dir / "instructions"
+        instructions_dir.mkdir(exist_ok=True)
+
+        # Create repository object
+        library_repo = LibraryRepository(
+            namespace=namespace,
+            name=repo_name,
+            description=repo_description,
+            url=repo_url,
+            author=repo_author,
+            version=repo_version,
+            downloaded_at=datetime.now(),
+            alias=alias,
+            instructions=instructions,
+        )
+
+        # Update index
+        index = self.load_index()
+        index[namespace] = library_repo
+        self.save_index(index)
+
+        return library_repo
+
+    def remove_repository(self, namespace: str) -> bool:
+        """
+        Remove a repository from the library.
+
+        Args:
+            namespace: Repository namespace to remove
+
+        Returns:
+            True if removed, False if not found
+        """
+        # Load index
+        index = self.load_index()
+
+        if namespace not in index:
+            return False
+
+        # Remove from index
+        del index[namespace]
+        self.save_index(index)
+
+        # Remove directory
+        repo_dir = self.library_dir / namespace
+        if repo_dir.exists():
+            shutil.rmtree(repo_dir)
+
+        return True
+
+    def get_repository(self, namespace: str) -> Optional[LibraryRepository]:
+        """
+        Get a repository by namespace.
+
+        Args:
+            namespace: Repository namespace
+
+        Returns:
+            LibraryRepository or None if not found
+        """
+        index = self.load_index()
+        return index.get(namespace)
+
+    def get_repository_by_url(self, url: str) -> Optional[LibraryRepository]:
+        """
+        Find a repository by its source URL.
+
+        Args:
+            url: Repository URL (will be normalized for comparison)
+
+        Returns:
+            LibraryRepository or None if not found
+        """
+        # Normalize path for comparison
+        if not url.startswith(("http://", "https://", "git@")):
+            url = str(Path(url).resolve())
+
+        index = self.load_index()
+        for repo in index.values():
+            repo_url = repo.url
+            # Normalize repo URL for comparison
+            if not repo_url.startswith(("http://", "https://", "git@")):
+                repo_url = str(Path(repo_url).resolve())
+
+            if repo_url == url:
+                return repo
+
+        return None
+
+    def list_repositories(self) -> list[LibraryRepository]:
+        """
+        List all repositories in the library.
+
+        Returns:
+            List of LibraryRepository objects
+        """
+        index = self.load_index()
+        return list(index.values())
+
+    def list_instructions(self) -> list[LibraryInstruction]:
+        """
+        List all instructions across all repositories.
+
+        Returns:
+            Flattened list of all LibraryInstruction objects
+        """
+        instructions = []
+        for repo in self.list_repositories():
+            instructions.extend(repo.instructions)
+        return instructions
+
+    def get_instruction(self, instruction_id: str) -> Optional[LibraryInstruction]:
+        """
+        Get an instruction by ID.
+
+        Args:
+            instruction_id: Instruction ID (namespace/name)
+
+        Returns:
+            LibraryInstruction or None if not found
+        """
+        for instruction in self.list_instructions():
+            if instruction.id == instruction_id:
+                return instruction
+        return None
+
+    def get_instructions_by_name(self, name: str) -> list[LibraryInstruction]:
+        """
+        Get all instructions with a given name (may be multiple from different repos).
+
+        Args:
+            name: Instruction name
+
+        Returns:
+            List of LibraryInstruction objects with matching name
+        """
+        return [inst for inst in self.list_instructions() if inst.name == name]
+
+    def get_instructions_by_source_and_name(self, source_alias: str, name: str) -> list[LibraryInstruction]:
+        """
+        Get instructions by source alias and name.
+
+        Args:
+            source_alias: Source alias to filter by
+            name: Instruction name
+
+        Returns:
+            List of LibraryInstruction objects matching source and name
+        """
+        # Find repositories matching the source alias
+        matching_repos = []
+        for repo in self.list_repositories():
+            if repo.alias and repo.alias.lower() == source_alias.lower():
+                matching_repos.append(repo)
+
+        # Get instructions from matching repos
+        return [inst for repo in matching_repos for inst in repo.instructions if inst.name == name]
+
+    def search_instructions(
+        self,
+        query: Optional[str] = None,
+        repo_namespace: Optional[str] = None,
+        tags: Optional[list[str]] = None,
+    ) -> list[LibraryInstruction]:
+        """
+        Search instructions with filters.
+
+        Args:
+            query: Search query (matches name or description)
+            repo_namespace: Filter by repository namespace
+            tags: Filter by tags (instruction must have at least one matching tag)
+
+        Returns:
+            List of matching LibraryInstruction objects
+        """
+        instructions = self.list_instructions()
+
+        # Filter by query
+        if query:
+            query_lower = query.lower()
+            instructions = [
+                inst
+                for inst in instructions
+                if query_lower in inst.name.lower() or query_lower in inst.description.lower()
+            ]
+
+        # Filter by repo
+        if repo_namespace:
+            instructions = [inst for inst in instructions if inst.repo_namespace == repo_namespace]
+
+        # Filter by tags
+        if tags:
+            instructions = [inst for inst in instructions if any(tag in inst.tags for tag in tags)]
+
+        return instructions
+
+    def get_instruction_file_path(self, instruction_id: str) -> Optional[Path]:
+        """
+        Get the absolute path to an instruction file.
+
+        Args:
+            instruction_id: Instruction ID (namespace/name)
+
+        Returns:
+            Path to instruction file or None if not found
+        """
+        instruction = self.get_instruction(instruction_id)
+        if not instruction:
+            return None
+
+        return Path(instruction.file_path)
+
+    def get_versioned_namespace(self, repo_identifier: str, ref: str) -> str:
+        """
+        Generate filesystem-safe namespace for repo@ref.
+
+        Args:
+            repo_identifier: Repository identifier (URL or name)
+            ref: Git reference (tag, branch, or commit)
+
+        Returns:
+            Versioned namespace string (e.g., 'github.com_owner_repo@v1.0.0')
+        """
+        import re
+
+        # Get base namespace without version
+        base_namespace = self.get_repo_namespace(repo_identifier, "")
+
+        # Sanitize ref for filesystem (replace special chars)
+        # Handle refs like 'feature/new-feature' or 'refs/tags/v1.0.0'
+        safe_ref = re.sub(r"[^a-zA-Z0-9._-]", "_", ref)
+
+        return f"{base_namespace}@{safe_ref}"
+
+    def list_repository_versions(self, repo_identifier: str) -> list[tuple[str, str]]:
+        """
+        List all downloaded versions of a repository.
+
+        Args:
+            repo_identifier: Repository identifier (URL or base namespace)
+
+        Returns:
+            List of tuples (version_ref, full_namespace) for all versions found
+        """
+        import re
+
+        # Get base namespace pattern to match
+        base_namespace = self.get_repo_namespace(repo_identifier, "")
+
+        # Load index
+        index = self.load_index()
+
+        # Find all namespaces that match base pattern with version suffix
+        versions = []
+        pattern = re.compile(rf"^{re.escape(base_namespace)}@(.+)$")
+
+        for namespace in index.keys():
+            match = pattern.match(namespace)
+            if match:
+                version_ref = match.group(1)
+                # Convert sanitized ref back (e.g., 'feature_new-feature' -> original might vary)
+                versions.append((version_ref, namespace))
+
+        # Also check if there's a non-versioned namespace (legacy support)
+        if base_namespace in index:
+            versions.append(("default", base_namespace))
+
+        return versions

aiconfigkit/storage/mcp_tracker.py

@@ -0,0 +1 @@
+"""Track active MCP sets per project."""

aiconfigkit/storage/package_tracker.py

@@ -0,0 +1,234 @@
+"""Package installation tracking and persistence."""
+
+import json
+import logging
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+from aiconfigkit.core.models import (
+    InstallationScope,
+    InstallationStatus,
+    PackageInstallationRecord,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class PackageTracker:
+    """
+    Manages tracking of installed packages.
+
+    Stores package installation records in <project-root>/.ai-config-kit/packages.json
+    for project-level tracking.
+    """
+
+    def __init__(self, tracker_file: Path):
+        """
+        Initialize package tracker.
+
+        Args:
+            tracker_file: Path to package tracker JSON file
+        """
+        self.tracker_file = tracker_file
+        self._ensure_tracker_file()
+
+    def _ensure_tracker_file(self) -> None:
+        """Ensure tracker file and directory exist."""
+        self.tracker_file.parent.mkdir(parents=True, exist_ok=True)
+
+        if not self.tracker_file.exists():
+            # Create empty tracker file
+            self._write_records([])
+
+    def _read_records(self) -> list[PackageInstallationRecord]:
+        """Read all package installation records from file."""
+        try:
+            with open(self.tracker_file, "r", encoding="utf-8") as f:
+                data = json.load(f)
+
+            records = []
+            for item in data:
+                try:
+                    record = PackageInstallationRecord.from_dict(item)
+                    records.append(record)
+                except Exception as e:
+                    logger.warning(f"Skipping invalid package record: {e}")
+                    continue
+
+            return records
+
+        except json.JSONDecodeError as e:
+            logger.error(f"Invalid JSON in tracker file {self.tracker_file}: {e}")
+            return []
+        except FileNotFoundError:
+            logger.debug(f"Tracker file not found: {self.tracker_file}, will create on first write")
+            return []
+
+    def _write_records(self, records: list[PackageInstallationRecord]) -> None:
+        """Write all package installation records to file."""
+        try:
+            data = [record.to_dict() for record in records]
+
+            self.tracker_file.parent.mkdir(parents=True, exist_ok=True)
+
+            with open(self.tracker_file, "w", encoding="utf-8") as f:
+                json.dump(data, f, indent=2, ensure_ascii=False)
+
+            logger.debug(f"Wrote {len(records)} package records to {self.tracker_file}")
+
+        except Exception as e:
+            logger.error(f"Failed to write package tracker: {e}")
+            raise
+
+    def record_installation(self, record: PackageInstallationRecord) -> None:
+        """
+        Record a new package installation.
+
+        If a package with the same name and scope already exists, it will be updated.
+
+        Args:
+            record: Package installation record to save
+        """
+        records = self._read_records()
+
+        # Check if package already exists (same name and scope)
+        existing_index = None
+        for i, existing in enumerate(records):
+            if existing.package_name == record.package_name and existing.scope == record.scope:
+                existing_index = i
+                break
+
+        if existing_index is not None:
+            # Update existing record
+            logger.info(f"Updating existing package installation: {record.package_name}")
+            records[existing_index] = record
+        else:
+            # Add new record
+            logger.info(f"Recording new package installation: {record.package_name}")
+            records.append(record)
+
+        self._write_records(records)
+
+    def get_installed_packages(self, scope: Optional[InstallationScope] = None) -> list[PackageInstallationRecord]:
+        """
+        Get all installed packages.
+
+        Args:
+            scope: Filter by installation scope (optional)
+
+        Returns:
+            List of package installation records
+        """
+        records = self._read_records()
+
+        if scope:
+            records = [r for r in records if r.scope == scope]
+
+        return records
+
+    def get_package(self, package_name: str, scope: InstallationScope) -> Optional[PackageInstallationRecord]:
+        """
+        Get installation record for a specific package.
+
+        Args:
+            package_name: Name of the package
+            scope: Installation scope
+
+        Returns:
+            Package installation record, or None if not found
+        """
+        records = self._read_records()
+
+        for record in records:
+            if record.package_name == package_name and record.scope == scope:
+                return record
+
+        return None
+
+    def update_package(
+        self,
+        package_name: str,
+        scope: InstallationScope,
+        status: Optional[InstallationStatus] = None,
+        version: Optional[str] = None,
+    ) -> bool:
+        """
+        Update an existing package installation record.
+
+        Args:
+            package_name: Name of the package to update
+            scope: Installation scope
+            status: New installation status (optional)
+            version: New version (optional)
+
+        Returns:
+            True if package was found and updated, False otherwise
+        """
+        records = self._read_records()
+
+        for record in records:
+            if record.package_name == package_name and record.scope == scope:
+                # Update fields
+                if status:
+                    record.status = status
+                if version:
+                    record.version = version
+                record.updated_at = datetime.now()
+
+                self._write_records(records)
+                logger.info(f"Updated package installation: {package_name}")
+                return True
+
+        logger.warning(f"Package not found for update: {package_name} (scope: {scope.value})")
+        return False
+
+    def remove_package(self, package_name: str, scope: InstallationScope) -> bool:
+        """
+        Remove a package installation record.
+
+        Args:
+            package_name: Name of the package to remove
+            scope: Installation scope
+
+        Returns:
+            True if package was found and removed, False otherwise
+        """
+        records = self._read_records()
+        original_count = len(records)
+
+        # Filter out the package to remove
+        records = [r for r in records if not (r.package_name == package_name and r.scope == scope)]
+
+        if len(records) < original_count:
+            self._write_records(records)
+            logger.info(f"Removed package installation: {package_name}")
+            return True
+
+        logger.warning(f"Package not found for removal: {package_name} (scope: {scope.value})")
+        return False
+
+    def is_package_installed(self, package_name: str, scope: InstallationScope) -> bool:
+        """
+        Check if a package is installed.
+
+        Args:
+            package_name: Name of the package
+            scope: Installation scope
+
+        Returns:
+            True if package is installed, False otherwise
+        """
+        return self.get_package(package_name, scope) is not None
+
+    def get_package_count(self, scope: Optional[InstallationScope] = None) -> int:
+        """
+        Get count of installed packages.
+
+        Args:
+            scope: Filter by installation scope (optional)
+
+        Returns:
+            Number of installed packages
+        """
+        return len(self.get_installed_packages(scope))