lite-kits 0.1.0__py3-none-any.whl → 0.3.1__py3-none-any.whl

lite_kits/core/installer.py

@@ -0,0 +1,322 @@
+"""
+Manifest-driven installer for lite-kits.
+
+Orchestrates detection, validation, and file operations.
+Delegates to specialized modules for specific tasks.
+"""
+
+import shutil
+from pathlib import Path
+from typing import Dict, List, Optional
+
+from .conflict_checker import ConflictChecker
+from .detector import Detector
+from .manifest import KitManifest
+from .validator import Validator
+
+
+class Installer:
+    """Main installer orchestrator."""
+
+    def __init__(
+        self,
+        target_dir: Path,
+        kits: Optional[List[str]] = None,
+        force: bool = False,
+        agent: Optional[str] = None,
+        shell: Optional[str] = None,
+    ):
+        """
+        Initialize installer.
+
+        Args:
+            target_dir: Target spec-kit project directory
+            kits: List of kits to install (None = use default from manifest)
+            force: Skip confirmations and overwrite existing files
+            agent: Explicit agent preference (None = auto-detect)
+            shell: Explicit shell preference (None = auto-detect)
+        """
+        self.target_dir = Path(target_dir).resolve()
+        self.kits_dir = Path(__file__).parent.parent / "kits"
+
+        # Load manifest
+        self.manifest = KitManifest(self.kits_dir)
+
+        # Initialize specialized modules
+        self.detector = Detector(self.target_dir, self.manifest)
+        self.validator = Validator(self.target_dir, self.manifest)
+        self.conflict_checker = ConflictChecker(
+            self.target_dir,
+            self.kits_dir,
+            self.manifest
+        )
+
+        # Operational modes
+        self.force = force
+
+        # Preferences
+        self.preferred_agent = agent
+        self.preferred_shell = shell
+
+        # Kits to install
+        self.kits = kits or [self.manifest.get_default_kit()]
+
+        # Validate kit names
+        self._validate_kit_names()
+
+    def _validate_kit_names(self):
+        """Validate kit names against manifest."""
+        valid_kits = set(self.manifest.get_kit_names())
+        invalid = set(self.kits) - valid_kits
+        if invalid:
+            valid_list = ', '.join(sorted(valid_kits))
+            raise ValueError(f"Invalid kit(s): {invalid}. Valid: {valid_list}")
+
+    def is_spec_kit_project(self) -> bool:
+        """Check if target is a spec-kit project."""
+        return self.detector.is_spec_kit_project()
+
+    def is_kit_installed(self, kit_name: str) -> bool:
+        """Check if kit is installed."""
+        return self.validator.is_kit_installed(kit_name)
+
+    def preview_installation(self) -> Dict:
+        """Preview installation without making changes."""
+        agents = self.detector.detect_agents(self.preferred_agent)
+        shells = self.detector.detect_shells(self.preferred_shell)
+
+        preview = {
+            "kits": [],
+            "conflicts": [],
+            "warnings": [],
+            "agents": agents,
+            "shells": shells,
+        }
+
+        if not agents:
+            supported = [
+                name for name, config in self.manifest.manifest.get('agents', {}).items()
+                if config.get('supported', False)
+            ]
+            preview['warnings'].append(f"No AI agents detected. Supported: {', '.join(supported)}")
+            return preview
+
+        conflicts = self.conflict_checker.check_conflicts(self.kits, agents, shells)
+        preview['conflicts'] = conflicts['overwrites']
+
+        for kit_name in self.kits:
+            kit_preview = self._preview_kit(kit_name, agents, shells)
+            preview['kits'].append(kit_preview)
+
+        return preview
+
+    def _preview_kit(self, kit_name: str, agents: List[str], shells: List[str]) -> Dict:
+        """Preview installation for a single kit."""
+        kit_info = self.manifest.get_kit(kit_name)
+        kit_preview = {
+            "name": kit_info['name'],
+            "new_files": [],
+            "modified_files": [],
+            "new_directories": [],
+        }
+
+        for agent in agents:
+            files = self.manifest.get_kit_files(kit_name, agent=agent)
+            self._preview_files(files, kit_preview)
+
+        for shell in shells:
+            files = self.manifest.get_kit_files(kit_name, agent=shell)
+            self._preview_files(files, kit_preview)
+
+        # Get other files (not commands\prompts\scripts - those are handled above)
+        all_files = self.manifest.get_kit_files(kit_name, agent=None)
+        for file_info in all_files:
+            if file_info.get('type') in ['command', 'prompt', 'script']:
+                continue  # Already handled by agent/shell sections above
+            self._preview_files([file_info], kit_preview)
+
+        return kit_preview
+
+    def _preview_files(self, files: List[Dict], preview: Dict):
+        """Preview a list of files."""
+        for file_info in files:
+            if file_info.get('status') == 'planned':
+                continue
+
+            # Normalize paths to use backslashes for Windows display
+            target_path = str(file_info['path']).replace("/", "\\")
+            target_full = self.target_dir / file_info['path']
+
+            if target_full.exists():
+                if target_path not in preview["modified_files"]:
+                    preview["modified_files"].append(target_path)
+            else:
+                if target_path not in preview["new_files"]:
+                    preview["new_files"].append(target_path)
+
+                parent_dir = str(target_full.parent.relative_to(self.target_dir))
+                if parent_dir not in preview["new_directories"]:
+                    if not target_full.parent.exists():
+                        preview["new_directories"].append(parent_dir)
+
+    def install(self) -> Dict:
+        """Install kits to target project."""
+        result = {
+            "success": False,
+            "installed": [],
+            "skipped": [],
+            "error": None,
+        }
+
+        try:
+            agents = self.detector.detect_agents(self.preferred_agent)
+            shells = self.detector.detect_shells(self.preferred_shell)
+
+            if not agents:
+                supported = [
+                    name for name, config in self.manifest.manifest.get('agents', {}).items()
+                    if config.get('supported', False)
+                ]
+                result["error"] = (
+                    f"No supported AI interface found. Supported: {', '.join(supported)}. "
+                    r"To enable AI interface support, create a '.claude\' or '.github\prompts\' directory in your project."
+                )
+                return result
+
+            if not self.force:
+                conflicts = self.conflict_checker.check_conflicts(self.kits, agents, shells)
+
+                if conflicts['has_conflicts']:
+                    result["conflicts"] = conflicts['overwrites']
+                    result["error"] = f"Found {len(conflicts['conflicts'])} file conflicts. Use --force to overwrite."
+                    return result
+
+            options = self.manifest.manifest.get('options', {})
+
+            for kit_name in self.kits:
+                self._install_kit(kit_name, agents, shells, options, result)
+
+            result["success"] = True
+
+            if options.get('validate_on_install', True):
+                result["validation"] = self.validator.validate_all()
+
+        except Exception as e:
+            result["error"] = str(e)
+
+        return result
+
+    def _install_kit(self, kit_name: str, agents: List[str], shells: List[str], options: Dict, result: Dict):
+        """Install a single kit."""
+        skip_existing = options.get('skip_existing', True)
+
+        for agent in agents:
+            files = self.manifest.get_kit_files(kit_name, agent=agent)
+            self._install_files(files, skip_existing, result)
+
+        for shell in shells:
+            files = self.manifest.get_kit_files(kit_name, agent=shell)
+            self._install_files(files, skip_existing, result)
+
+        all_files = self.manifest.get_kit_files(kit_name, agent=None)
+        for file_info in all_files:
+            if file_info.get('type') in ['command', 'prompt', 'script']:
+                continue
+            self._install_files([file_info], skip_existing, result)
+
+    def _install_files(self, files: List[Dict], skip_existing: bool, result: Dict):
+        """Install a list of files."""
+        for file_info in files:
+            if file_info.get('status') == 'planned':
+                result["skipped"].append(f"{file_info['path']} (planned)")
+                continue
+
+            target_path = self.target_dir / file_info['path']
+
+            if skip_existing and target_path.exists() and not self.force:
+                result["skipped"].append(file_info['path'])
+                continue
+
+            self._copy_file(file_info['source'], file_info['path'])
+            result["installed"].append(file_info['path'])
+
+    def validate(self) -> Dict:
+        """Validate all installed kits."""
+        return self.validator.validate_all()
+
+    def preview_removal(self) -> Dict:
+        """Preview files that would be removed."""
+        preview = {
+            "kits": [],
+            "total_files": 0,
+        }
+
+        for kit_name in self.kits:
+            kit_info = self.manifest.get_kit(kit_name)
+            files_to_remove = []
+
+            all_files = self.manifest.get_kit_files(kit_name, agent=None)
+
+            for file_info in all_files:
+                target_path = self.target_dir / file_info['path']
+                if target_path.exists():
+                    files_to_remove.append(file_info['path'])
+
+            if files_to_remove:
+                preview["kits"].append({
+                    'name': kit_info['name'],
+                    'files': files_to_remove
+                })
+                preview["total_files"] += len(files_to_remove)
+
+        return preview
+
+    def remove(self) -> Dict:
+        """Remove kits from project."""
+        result = {
+            "success": False,
+            "removed": [],
+            "not_found": [],
+            "error": None,
+        }
+
+        try:
+            for kit_name in self.kits:
+                kit_info = self.manifest.get_kit(kit_name)
+                removed_files = []
+                not_found_files = []
+
+                all_files = self.manifest.get_kit_files(kit_name, agent=None)
+
+                for file_info in all_files:
+                    target_path = self.target_dir / file_info['path']
+
+                    if target_path.exists():
+                        target_path.unlink()
+                        removed_files.append(file_info['path'])
+                    else:
+                        not_found_files.append(file_info['path'])
+
+                if removed_files:
+                    result["removed"].append({'kit': kit_info['name'], 'files': removed_files})
+
+                if not_found_files:
+                    result["not_found"].extend(not_found_files)
+
+            result["success"] = True
+
+        except Exception as e:
+            result["error"] = str(e)
+
+        return result
+
+    def _copy_file(self, kit_relative_path: str, target_relative_path: str):
+        """Copy file from kits/ to target project."""
+        source = self.kits_dir / kit_relative_path
+        target = self.target_dir / target_relative_path
+
+        if not source.exists():
+            raise FileNotFoundError(f"Kit file not found: {source}")
+
+        target.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(source, target)

lite_kits/core/manifest.py

@@ -0,0 +1,146 @@
+"""
+Kit manifest loader and utilities.
+
+Loads kit definitions from kits.yaml and provides helpers for installation,
+validation, and status checking.
+"""
+
+from pathlib import Path
+from typing import Dict, List, Optional
+import yaml
+
+
+class KitManifest:
+    """Loads and provides access to kit definitions from kits.yaml"""
+
+    def __init__(self, kits_dir: Path):
+        """
+        Initialize manifest loader.
+
+        Args:
+            kits_dir: Path to kits directory containing kits.yaml
+        """
+        self.kits_dir = kits_dir
+        self.manifest_path = kits_dir / "kits.yaml"
+        self._manifest = None
+
+    @property
+    def manifest(self) -> Dict:
+        """Load and cache manifest data"""
+        if self._manifest is None:
+            with open(self.manifest_path, encoding='utf-8') as f:
+                self._manifest = yaml.safe_load(f)
+        return self._manifest
+
+    def get_kit(self, kit_name: str) -> Optional[Dict]:
+        """Get kit definition by name"""
+        return self.manifest['kits'].get(kit_name)
+
+    def get_all_kits(self) -> Dict[str, Dict]:
+        """Get all kit definitions"""
+        return self.manifest['kits']
+
+    def get_kit_names(self) -> List[str]:
+        """Get list of all kit names"""
+        return list(self.manifest['kits'].keys())
+
+    def get_recommended_kits(self) -> List[str]:
+        """Get list of recommended kit names"""
+        return [
+            name for name, kit in self.manifest['kits'].items()
+            if kit.get('recommended', False)
+        ]
+
+    def get_default_kit(self) -> str:
+        """Get default kit name"""
+        return self.manifest['options']['default_kit']
+
+    def get_kit_files(self, kit_name: str, agent: Optional[str] = None) -> List[Dict]:
+        """
+        Get list of files for a kit.
+
+        Args:
+            kit_name: Name of kit
+            agent: Optional agent filter ('claude', 'copilot', None for all)
+
+        Returns:
+            List of file dicts with 'path', 'source', 'required' keys
+        """
+        kit = self.get_kit(kit_name)
+        if not kit:
+            return []
+
+        files = []
+        file_groups = kit.get('files', {})
+
+        # Map agent names to file groups
+        agent_groups = {
+            'claude': ['claude'],
+            'copilot': ['copilot'],
+            None: list(file_groups.keys())  # All groups
+        }
+
+        groups_to_include = agent_groups.get(agent, [])
+
+        for group_name in groups_to_include:
+            if group_name in file_groups:
+                files.extend(file_groups[group_name])
+
+        return files
+
+    def get_kit_markers(self, kit_name: str) -> List[str]:
+        """
+        Get marker files for kit detection.
+
+        Args:
+            kit_name: Name of kit
+
+        Returns:
+            List of marker file paths
+        """
+        kit = self.get_kit(kit_name)
+        return kit.get('markers', []) if kit else []
+
+    def get_kit_commands(self, kit_name: str) -> List[Dict]:
+        """
+        Get list of commands for a kit.
+
+        Args:
+            kit_name: Name of kit
+
+        Returns:
+            List of command dicts with 'name', 'description', 'status' keys
+        """
+        kit = self.get_kit(kit_name)
+        return kit.get('commands', []) if kit else []
+
+    def get_agent_config(self, agent: str) -> Optional[Dict]:
+        """
+        Get agent configuration.
+
+        Args:
+            agent: Agent name ('claude', 'copilot')
+
+        Returns:
+            Agent config dict or None
+        """
+        return self.manifest.get('agents', {}).get(agent)
+
+    def validate_kit_name(self, kit_name: str) -> bool:
+        """Check if kit name is valid"""
+        return kit_name in self.get_kit_names()
+
+    def get_kit_description(self, kit_name: str) -> str:
+        """Get kit description"""
+        kit = self.get_kit(kit_name)
+        return kit.get('description', '') if kit else ''
+
+    def get_kit_icon(self, kit_name: str) -> str:
+        """Get kit icon emoji"""
+        kit = self.get_kit(kit_name)
+        return kit.get('icon', '📦') if kit else '📦'
+
+    def is_recommended(self, kit_name: str) -> bool:
+        """Check if kit is recommended"""
+        kit = self.get_kit(kit_name)
+        return kit.get('recommended', False) if kit else False

lite_kits/core/validator.py

@@ -0,0 +1,146 @@
+"""
+Kit validation and integrity checking.
+
+Validates installed kits, checks for missing/corrupted files.
+"""
+
+from pathlib import Path
+from typing import Dict
+
+from .manifest import KitManifest
+
+
+class Validator:
+    """Validates kit installations."""
+
+    def __init__(self, target_dir: Path, manifest: KitManifest):
+        """
+        Initialize validator.
+
+        Args:
+            target_dir: Target project directory
+            manifest: Loaded kit manifest
+        """
+        self.target_dir = target_dir
+        self.manifest = manifest
+
+    def validate_all(self) -> Dict:
+        """
+        Validate all kits.
+
+        Returns:
+            Validation results for all kits
+        """
+        checks = {}
+        options = self.manifest.manifest.get('options', {})
+
+        for kit_name in self.manifest.get_kit_names():
+            checks[kit_name] = self.validate_kit(kit_name, options)
+
+        # Overall validation passes if at least one kit is fully installed
+        any_installed = any(
+            check['status'] == 'installed'
+            for check in checks.values()
+        )
+
+        return {
+            "valid": any_installed,
+            "checks": checks,
+        }
+
+    def validate_kit(self, kit_name: str, options: Dict) -> Dict:
+        """
+        Validate a single kit.
+
+        Args:
+            kit_name: Name of kit to validate
+            options: Options from manifest
+
+        Returns:
+            Validation result for this kit
+        """
+        kit_info = self.manifest.get_kit(kit_name)
+        markers = self.manifest.get_kit_markers(kit_name)
+
+        # Check if kit is installed
+        kit_installed = any(
+            (self.target_dir / marker).exists()
+            for marker in markers
+        )
+
+        if not kit_installed:
+            return {
+                "passed": True,
+                "status": "not_installed",
+                "message": f"{kit_info['name']}: not installed",
+            }
+
+        # Kit is installed, validate files
+        all_files = self.manifest.get_kit_files(kit_name, agent=None)
+
+        missing = []
+        corrupted = []
+        outdated = []
+
+        for file_info in all_files:
+            # Skip non-required files
+            if not file_info.get('required', True):
+                continue
+
+            # Skip planned files
+            if file_info.get('status') == 'planned':
+                continue
+
+            target_path = self.target_dir / file_info['path']
+
+            # Check exists
+            if not target_path.exists():
+                missing.append(file_info['path'])
+                continue
+
+            # Check integrity
+            if options.get('check_file_integrity', True):
+                min_size = options.get('min_file_size', 100)
+                if target_path.stat().st_size < min_size:
+                    corrupted.append(file_info['path'])
+
+            # Check if outdated (differs from source)
+            # (Placeholder for now, can add diff later)
+
+        # Build result
+        if missing or corrupted:
+            issues = []
+            if missing:
+                issues.append(f"{len(missing)} missing")
+            if corrupted:
+                issues.append(f"{len(corrupted)} corrupted")
+
+            return {
+                "passed": False,
+                "status": "partial",
+                "message": f"{kit_info['name']}: {', '.join(issues)}",
+                "missing_files": missing,
+                "corrupted_files": corrupted,
+            }
+
+        return {
+            "passed": True,
+            "status": "installed",
+            "message": f"{kit_info['name']}: all files present",
+        }
+
+    def is_kit_installed(self, kit_name: str) -> bool:
+        """
+        Quick check if kit is installed.
+
+        Args:
+            kit_name: Name of kit
+
+        Returns:
+            True if any marker exists
+        """
+        markers = self.manifest.get_kit_markers(kit_name)
+        return any(
+            (self.target_dir / marker).exists()
+            for marker in markers
+        )

lite_kits/kits/README.md

@@ -6,11 +6,11 @@ This directory contains modular add-on kits that can be installed independently
 
 ### ✅ Recommended (Default Installation)
 
-#### 1. **project-kit**
-**Commands**: `/orient` ⭐, `/review`, `/audit`, `/stats`
+#### 1. **dev-kit**
+**Commands**: `/orient` ⭐, `/audit`, `/stats`
 **Scripts**: Enhanced feature creation with custom naming
 
-Essential project-level utilities combining agent orientation, code quality checks, and vanilla spec-kit enhancements.
+Essential project-level utilities combining agent orientation, quality checks, and vanilla spec-kit enhancements.
 
 **Installs to**:
 - `.claude/commands/` (Claude Code)
@@ -21,10 +21,10 @@ Essential project-level utilities combining agent orientation, code quality chec
 
 ---
 
-#### 2. **git-kit**
-**Commands**: `/commit`, `/pr`, `/sync`, `/cleanup`
+#### 2. **dev-kit**
+**Commands**: `/commit`, `/pr`, `/review`, `/sync`, `/cleanup`
 
-Git workflow automation with smart commits, PR creation, sync status, and cleanup operations. Includes ASCII visualization for better readability.
+Git workflow automation with smart commits, PR creation, code review, sync status, and cleanup operations. Includes ASCII visualization for better readability.
 
 **Installs to**:
 - `.claude/commands/` (Claude Code)
@@ -41,14 +41,14 @@ Git workflow automation with smart commits, PR creation, sync status, and cleanu
 
 Multi-agent coordination structure for complex projects with multiple AI agents working in parallel.
 
-**Dependencies**: Requires `project-kit` (for `/review`) and `git-kit` (for `/commit`, `/pr`)
+**Dependencies**: None (standalone)
 
 **Installs to**:
 - `.specify/memory/pr-workflow-guide.md`
 - `.specify/memory/git-worktrees-protocol.md`
 - `specs/*/collaboration/` (template, created per-feature)
 
-**Use case**: Large projects with multiple AI agents collaborating (e.g., Claude Code + Copilot).
+**Use case**: Large projects with multiple AI agents collaborating (e.g., Claude Code + Copilot). Works best when combined with dev-kit and dev-kit.
 
 ---
 
@@ -56,9 +56,9 @@ Multi-agent coordination structure for complex projects with multiple AI agents
 
 | Kit | Default | Target Users | Adds | Dependencies |
 |-----|---------|--------------|------|--------------|
-| **project** | ✅ Yes | Everyone | 4 commands + enhanced scripts | None |
+| **project** | ✅ Yes | Everyone | 3 commands + enhanced scripts | None |
 | **git** | ✅ Yes | Everyone | 4 commands with ASCII viz | None |
-| **multiagent** | ❌ No | Multi-agent projects | Collaboration structure | project, git |
+| **multiagent** | ❌ No | Multi-agent projects | Collaboration structure + /sync | None |
 
 ## Kit Structure
 
@@ -139,25 +139,24 @@ lite-kits remove -Kit git,project
 
 ## Kit Details
 
-### project-kit Commands
+### dev-kit Commands
 
 | Command | Description |
 |---------|-------------|
 | `/orient` | Agent orientation (read docs, check git, determine role) |
-| `/review` | Code review against constitution and best practices |
 | `/audit` | Security and quality audit |
 | `/stats` | Project statistics (LOC, test coverage, complexity) |
 
-### git-kit Commands
+### dev-kit Commands
 
 | Command | Description |
 |---------|-------------|
 | `/commit` | Smart commit with agent attribution |
 | `/pr` | Create pull request with auto-generated description |
-| `/sync` | Show sync status with ASCII visualization |
+| `/review` | Code review of staged changes against best practices |
 | `/cleanup` | Clean merged branches, stale worktrees |
 
-### project-kit Enhancements
+### dev-kit Enhancements
 
 | Enhancement | Description |
 |-------------|-------------|