solokit 0.1.1__py3-none-any.whl

solokit/init/template_installer.py

@@ -0,0 +1,424 @@
+"""
+Template Installer Module
+
+Handles template file installation with tier-based structure.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+import shutil
+from pathlib import Path
+from typing import Any, cast
+
+from solokit.core.exceptions import FileOperationError, TemplateNotFoundError
+
+logger = logging.getLogger(__name__)
+
+
+def load_template_registry() -> dict[str, Any]:
+    """
+    Load template registry from templates/template-registry.json.
+
+    Returns:
+        Template registry dictionary
+
+    Raises:
+        TemplateNotFoundError: If registry file not found
+        FileOperationError: If registry file is invalid JSON
+    """
+    registry_path = Path(__file__).parent.parent / "templates" / "template-registry.json"
+
+    if not registry_path.exists():
+        raise TemplateNotFoundError(
+            template_name="template-registry.json",
+            template_path=str(registry_path.parent),
+        )
+
+    try:
+        with open(registry_path) as f:
+            return cast(dict[str, Any], json.load(f))
+    except json.JSONDecodeError as e:
+        raise FileOperationError(
+            operation="parse",
+            file_path=str(registry_path),
+            details=f"Invalid JSON in template registry: {str(e)}",
+            cause=e,
+        )
+
+
+def get_template_info(template_id: str) -> dict[str, Any]:
+    """
+    Get template information from registry.
+
+    Args:
+        template_id: Template identifier (e.g., "saas_t3")
+
+    Returns:
+        Template metadata dictionary
+
+    Raises:
+        TemplateNotFoundError: If template not found in registry
+    """
+    registry = load_template_registry()
+
+    if template_id not in registry["templates"]:
+        available = ", ".join(registry["templates"].keys())
+        raise TemplateNotFoundError(
+            template_name=template_id,
+            template_path=f"Available templates: {available}",
+        )
+
+    return cast(dict[str, Any], registry["templates"][template_id])
+
+
+def get_template_directory(template_id: str) -> Path:
+    """
+    Get path to template directory.
+
+    Args:
+        template_id: Template identifier (e.g., "saas_t3")
+
+    Returns:
+        Path to template directory
+
+    Raises:
+        TemplateNotFoundError: If template directory doesn't exist
+    """
+    templates_root = Path(__file__).parent.parent / "templates"
+    template_dir = templates_root / template_id
+
+    if not template_dir.exists():
+        raise TemplateNotFoundError(template_name=template_id, template_path=str(templates_root))
+
+    return template_dir
+
+
+def copy_directory_tree(src: Path, dst: Path, skip_patterns: list[str] | None = None) -> int:
+    """
+    Recursively copy directory tree from src to dst.
+
+    Args:
+        src: Source directory
+        dst: Destination directory
+        skip_patterns: List of filename patterns to skip (e.g., [".template", "__pycache__"])
+
+    Returns:
+        Number of files copied
+
+    Raises:
+        FileOperationError: If copy operation fails
+    """
+    if skip_patterns is None:
+        skip_patterns = []
+
+    files_copied = 0
+
+    try:
+        # Create destination directory
+        dst.mkdir(parents=True, exist_ok=True)
+
+        # Copy all files and subdirectories
+        for item in src.iterdir():
+            # Skip patterns
+            if any(pattern in item.name for pattern in skip_patterns):
+                continue
+
+            src_item = src / item.name
+            dst_item = dst / item.name
+
+            if src_item.is_dir():
+                files_copied += copy_directory_tree(src_item, dst_item, skip_patterns)
+            else:
+                shutil.copy2(src_item, dst_item)
+                files_copied += 1
+                logger.debug(f"Copied {src_item} -> {dst_item}")
+
+    except Exception as e:
+        raise FileOperationError(
+            operation="copy",
+            file_path=str(src),
+            details=f"Failed to copy directory tree: {str(e)}",
+            cause=e,
+        )
+
+    return files_copied
+
+
+def replace_placeholders(content: str, replacements: dict[str, str]) -> str:
+    """
+    Replace placeholders in template content.
+
+    Args:
+        content: Template content with placeholders like {project_name}
+        replacements: Dictionary of placeholder -> value
+
+    Returns:
+        Content with placeholders replaced
+    """
+    result = content
+    for placeholder, value in replacements.items():
+        result = result.replace(f"{{{placeholder}}}", value)
+    return result
+
+
+def install_base_template(
+    template_id: str, project_root: Path, replacements: dict[str, str]
+) -> int:
+    """
+    Install base template files.
+
+    Args:
+        template_id: Template identifier
+        project_root: Project root directory
+        replacements: Placeholder replacements (e.g., {"project_name": "my-app"})
+
+    Returns:
+        Number of files copied
+
+    Raises:
+        TemplateNotFoundError: If template not found
+        FileOperationError: If installation fails
+    """
+    template_dir = get_template_directory(template_id)
+    base_dir = template_dir / "base"
+
+    if not base_dir.exists():
+        raise TemplateNotFoundError(
+            template_name=f"{template_id}/base", template_path=str(template_dir)
+        )
+
+    logger.info(f"Installing base template files from {template_id}...")
+
+    # Copy base files
+    files_copied = copy_directory_tree(
+        base_dir, project_root, skip_patterns=[".template", "__pycache__", ".pyc"]
+    )
+
+    # Process template files (files ending in .template)
+    for template_file in base_dir.rglob("*.template"):
+        relative_path = template_file.relative_to(base_dir)
+        # Remove .template extension for output file
+        output_path = project_root / relative_path.parent / relative_path.stem
+
+        try:
+            content = template_file.read_text()
+            processed_content = replace_placeholders(content, replacements)
+            output_path.parent.mkdir(parents=True, exist_ok=True)
+            output_path.write_text(processed_content)
+            logger.debug(f"Processed template: {template_file.name} -> {output_path.name}")
+            files_copied += 1
+        except Exception as e:
+            raise FileOperationError(
+                operation="process",
+                file_path=str(template_file),
+                details=f"Failed to process template file: {str(e)}",
+                cause=e,
+            )
+
+    logger.info(f"Installed {files_copied} base files")
+    return files_copied
+
+
+def install_tier_files(
+    template_id: str, tier: str, project_root: Path, replacements: dict[str, str]
+) -> int:
+    """
+    Install tier-specific files.
+
+    Args:
+        template_id: Template identifier
+        tier: Tier name (e.g., "tier-1-essential")
+        project_root: Project root directory
+        replacements: Placeholder replacements
+
+    Returns:
+        Number of files copied/processed
+
+    Raises:
+        TemplateNotFoundError: If tier directory not found
+        FileOperationError: If installation fails
+    """
+    template_dir = get_template_directory(template_id)
+    tier_dir = template_dir / tier
+
+    if not tier_dir.exists():
+        logger.warning(f"Tier directory not found: {tier_dir}")
+        return 0
+
+    logger.info(f"Installing {tier} files...")
+
+    # Copy tier files
+    files_copied = copy_directory_tree(
+        tier_dir, project_root, skip_patterns=[".template", "__pycache__", ".pyc"]
+    )
+
+    # Process template files
+    for template_file in tier_dir.rglob("*.template"):
+        relative_path = template_file.relative_to(tier_dir)
+
+        # Strip tier suffix from filename if present (e.g., package.json.tier4.template -> package.json)
+        # This allows tier files to overwrite the base file instead of creating separate tier files
+        filename_without_template = relative_path.stem  # Removes .template
+
+        # Remove tier suffixes: .tier1, .tier2, .tier3, .tier4
+        filename_without_tier = re.sub(r"\.tier[1-4]$", "", filename_without_template)
+
+        output_path = project_root / relative_path.parent / filename_without_tier
+
+        try:
+            content = template_file.read_text()
+            processed_content = replace_placeholders(content, replacements)
+            output_path.parent.mkdir(parents=True, exist_ok=True)
+            output_path.write_text(processed_content)
+            logger.debug(f"Processed template: {template_file.name} -> {output_path.name}")
+            files_copied += 1
+        except Exception as e:
+            raise FileOperationError(
+                operation="process",
+                file_path=str(template_file),
+                details=f"Failed to process template file: {str(e)}",
+                cause=e,
+            )
+
+    logger.info(f"Installed {files_copied} files from {tier}")
+    return files_copied
+
+
+def install_additional_option(
+    template_id: str, option: str, project_root: Path, replacements: dict[str, str]
+) -> int:
+    """
+    Install additional option files (CI/CD, Docker, etc.).
+
+    Args:
+        template_id: Template identifier
+        option: Option name (e.g., "ci-cd", "docker")
+        project_root: Project root directory
+        replacements: Placeholder replacements
+
+    Returns:
+        Number of files copied
+
+    Raises:
+        FileOperationError: If installation fails
+    """
+    template_dir = get_template_directory(template_id)
+    option_dir = template_dir / option
+
+    if not option_dir.exists():
+        logger.warning(f"Option directory not found: {option_dir}")
+        return 0
+
+    logger.info(f"Installing {option} files...")
+
+    # Copy option files
+    files_copied = copy_directory_tree(
+        option_dir, project_root, skip_patterns=[".template", "__pycache__", ".pyc"]
+    )
+
+    # Process template files
+    for template_file in option_dir.rglob("*.template"):
+        relative_path = template_file.relative_to(option_dir)
+        output_path = project_root / relative_path.parent / relative_path.stem
+
+        try:
+            content = template_file.read_text()
+            processed_content = replace_placeholders(content, replacements)
+            output_path.parent.mkdir(parents=True, exist_ok=True)
+            output_path.write_text(processed_content)
+            logger.debug(f"Processed template: {template_file.name} -> {output_path.name}")
+            files_copied += 1
+        except Exception as e:
+            raise FileOperationError(
+                operation="process",
+                file_path=str(template_file),
+                details=f"Failed to process template file: {str(e)}",
+                cause=e,
+            )
+
+    logger.info(f"Installed {files_copied} files from {option}")
+    return files_copied
+
+
+def install_template(
+    template_id: str,
+    tier: str,
+    additional_options: list[str],
+    project_root: Path | None = None,
+) -> dict[str, Any]:
+    """
+    Install complete template with base + tier + options.
+
+    Args:
+        template_id: Template identifier (e.g., "saas_t3")
+        tier: Quality tier (e.g., "tier-2-standard")
+        additional_options: List of option names (e.g., ["ci-cd", "docker"])
+        project_root: Project root directory (defaults to current directory)
+
+    Returns:
+        Installation summary dictionary with file counts and paths
+
+    Raises:
+        TemplateNotFoundError: If template not found
+        FileOperationError: If installation fails
+    """
+    if project_root is None:
+        project_root = Path.cwd()
+
+    # Get template info
+    template_info = get_template_info(template_id)
+
+    # Prepare placeholder replacements
+    project_name = project_root.name
+    replacements = {
+        "project_name": project_name,
+        "project_description": f"A {template_info['display_name']} project",
+        "template_id": template_id,
+        "template_name": template_info["display_name"],
+    }
+
+    total_files = 0
+
+    # Install base template
+    total_files += install_base_template(template_id, project_root, replacements)
+
+    # Install tier files (cumulative - install all tiers up to selected)
+    tier_order = [
+        "tier-1-essential",
+        "tier-2-standard",
+        "tier-3-comprehensive",
+        "tier-4-production",
+    ]
+    selected_tier_index = tier_order.index(tier)
+
+    for i in range(selected_tier_index + 1):
+        tier_to_install = tier_order[i]
+        total_files += install_tier_files(template_id, tier_to_install, project_root, replacements)
+
+    # Install additional options
+    for option in additional_options:
+        # Map option keys to directory names
+        option_dir_map = {
+            "ci_cd": "ci-cd",
+            "docker": "docker",
+            "pre_commit": "pre-commit",
+            "env_templates": "env-templates",
+        }
+        option_dir = option_dir_map.get(option, option)
+        total_files += install_additional_option(
+            template_id, option_dir, project_root, replacements
+        )
+
+    logger.info(f"Template installation complete: {total_files} files installed")
+
+    return {
+        "template_id": template_id,
+        "template_name": template_info["display_name"],
+        "tier": tier,
+        "additional_options": additional_options,
+        "files_installed": total_files,
+        "project_root": str(project_root),
+    }

solokit/learning/__init__.py

@@ -0,0 +1 @@
+"""Learning system for capturing and curating development insights."""

solokit/learning/archiver.py

@@ -0,0 +1,115 @@
+"""Learning archiving module"""
+
+from __future__ import annotations
+
+import re
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from solokit.core.constants import MAX_LEARNING_AGE_SESSIONS
+from solokit.core.file_ops import load_json
+from solokit.core.logging_config import get_logger
+
+logger = get_logger(__name__)
+
+
+class LearningArchiver:
+    """Handles archiving of old, unreferenced learnings"""
+
+    def __init__(self, session_dir: Path, max_age_sessions: int = MAX_LEARNING_AGE_SESSIONS):
+        """
+        Initialize archiver
+
+        Args:
+            session_dir: Path to .session directory
+            max_age_sessions: Maximum age in sessions before archiving (default: 50)
+        """
+        self.session_dir = session_dir
+        self.max_age_sessions = max_age_sessions
+
+    def archive_old_learnings(
+        self, learnings: dict[str, Any], max_age_sessions: int | None = None
+    ) -> int:
+        """
+        Archive old, unreferenced learnings
+
+        Args:
+            learnings: Learnings dict with 'categories' key
+            max_age_sessions: Override default max age (optional)
+
+        Returns:
+            Number of learnings archived
+        """
+        max_age = max_age_sessions if max_age_sessions is not None else self.max_age_sessions
+        archived_count = 0
+        categories = learnings.get("categories", {})
+
+        # Get current session number from tracking
+        current_session = self._get_current_session_number()
+
+        for category_name, category_learnings in categories.items():
+            to_archive = []
+
+            for i, learning in enumerate(category_learnings):
+                # Extract session number from learned_in field
+                session_num = self._extract_session_number(learning.get("learned_in", ""))
+
+                # Archive if too old
+                if session_num and current_session > 0 and current_session - session_num > max_age:
+                    to_archive.append(i)
+
+            # Move to archive
+            archived = learnings.setdefault("archived", [])
+            for idx in sorted(to_archive, reverse=True):
+                learning = category_learnings.pop(idx)
+                learning["archived_from"] = category_name
+                learning["archived_at"] = datetime.now().isoformat()
+                archived.append(learning)
+                archived_count += 1
+
+        logger.info(f"Archived {archived_count} old learnings")
+        return archived_count
+
+    def _get_current_session_number(self) -> int:
+        """
+        Get the current session number from work items
+
+        Returns:
+            Maximum session number found, or 0 if none found
+        """
+        try:
+            work_items_path = self.session_dir / "tracking" / "work_items.json"
+            if work_items_path.exists():
+                data = load_json(work_items_path)
+                # Find max session number across all work items
+                max_session = 0
+                for item in data.get("work_items", {}).values():
+                    sessions = item.get("sessions", [])
+                    if sessions and isinstance(sessions, list):
+                        max_session = max(max_session, max(sessions))
+                return max_session
+        except (ValueError, KeyError, TypeError) as e:
+            logger.warning(f"Failed to get current session number: {e}")
+            return 0
+        return 0
+
+    def _extract_session_number(self, session_id: str) -> int:
+        """
+        Extract numeric session number from session ID
+
+        Args:
+            session_id: Session ID string (e.g., "session_001", "001", "1")
+
+        Returns:
+            Extracted session number or 0 if extraction fails
+        """
+        try:
+            # Handle formats like "session_001", "001", "1", etc.
+            match = re.search(r"\d+", session_id)
+            if match:
+                return int(match.group())
+        except (ValueError, AttributeError) as e:
+            logger.debug(f"Failed to extract session number from '{session_id}': {e}")
+            return 0
+        return 0

solokit/learning/categorizer.py

@@ -0,0 +1,126 @@
+"""Learning categorization module"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from solokit.core.logging_config import get_logger
+
+logger = get_logger(__name__)
+
+
+class LearningCategorizer:
+    """Handles automatic categorization of learnings based on content analysis"""
+
+    # Keyword sets for each category
+    ARCHITECTURE_KEYWORDS = [
+        "architecture",
+        "design",
+        "pattern",
+        "structure",
+        "component",
+        "module",
+        "layer",
+        "service",
+    ]
+
+    GOTCHA_KEYWORDS = [
+        "gotcha",
+        "trap",
+        "pitfall",
+        "mistake",
+        "error",
+        "bug",
+        "issue",
+        "problem",
+        "challenge",
+        "warning",
+    ]
+
+    PRACTICE_KEYWORDS = [
+        "best practice",
+        "convention",
+        "standard",
+        "guideline",
+        "recommendation",
+        "should",
+        "always",
+        "never",
+    ]
+
+    DEBT_KEYWORDS = [
+        "technical debt",
+        "refactor",
+        "cleanup",
+        "legacy",
+        "deprecated",
+        "workaround",
+        "hack",
+        "todo",
+    ]
+
+    PERFORMANCE_KEYWORDS = [
+        "performance",
+        "optimization",
+        "speed",
+        "slow",
+        "fast",
+        "efficient",
+        "memory",
+        "cpu",
+        "benchmark",
+    ]
+
+    def categorize_learning(self, learning: dict[str, Any]) -> str:
+        """
+        Automatically categorize a single learning based on content analysis
+
+        Args:
+            learning: Learning dict with 'content' field
+
+        Returns:
+            Category name string
+        """
+        content = learning.get("content", "").lower()
+
+        # Check for suggested type first
+        if "suggested_type" in learning:
+            suggested = learning["suggested_type"]
+            if suggested in [
+                "architecture_pattern",
+                "gotcha",
+                "best_practice",
+                "technical_debt",
+                "performance_insight",
+            ]:
+                return f"{suggested}s"  # Pluralize
+
+        # Score each category based on keywords
+        scores = {
+            "architecture_patterns": self._keyword_score(content, self.ARCHITECTURE_KEYWORDS),
+            "gotchas": self._keyword_score(content, self.GOTCHA_KEYWORDS),
+            "best_practices": self._keyword_score(content, self.PRACTICE_KEYWORDS),
+            "technical_debt": self._keyword_score(content, self.DEBT_KEYWORDS),
+            "performance_insights": self._keyword_score(content, self.PERFORMANCE_KEYWORDS),
+        }
+
+        # Return category with highest score, default to best_practices
+        max_category = max(scores.items(), key=lambda x: x[1])
+        return max_category[0] if max_category[1] > 0 else "best_practices"
+
+    def _keyword_score(self, text: str, keywords: list[str]) -> int:
+        """
+        Calculate keyword match score for text
+
+        Args:
+            text: Text to analyze (should be lowercased)
+            keywords: List of keywords to search for
+
+        Returns:
+            Number of keyword matches found
+        """
+        score = 0
+        for keyword in keywords:
+            if keyword in text:
+                score += 1
+        return score