spec-kitty-cli 0.12.1__py3-none-any.whl

specify_cli/upgrade/migrations/m_0_9_2_research_mission_templates.py

@@ -0,0 +1,221 @@
+"""Migration: Add missing task-prompt-template.md and tasks.md to research mission.
+
+This migration fixes a bug where research missions were missing:
+1. task-prompt-template.md - The YAML frontmatter template for WP files
+2. tasks.md command template - Instructions for generating WP files
+
+Without these templates, LLMs generating research WP files created files
+with **Status**: in the markdown body instead of lane: in YAML frontmatter,
+causing the review command to not find WPs ready for review.
+"""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+from ..registry import MigrationRegistry
+from .base import BaseMigration, MigrationResult
+
+
+@MigrationRegistry.register
+class ResearchMissionTemplatesMigration(BaseMigration):
+    """Add missing templates to research mission.
+
+    This fixes the bug where:
+    - Research WP files used **Status**: for_review in markdown body
+    - Review command expected lane: "for_review" in YAML frontmatter
+
+    The fix adds:
+    - templates/task-prompt-template.md with proper YAML frontmatter
+    - command-templates/tasks.md with instructions to use the template
+    """
+
+    migration_id = "0.9.2_research_mission_templates"
+    description = "Add missing task-prompt-template.md and tasks.md to research mission"
+    target_version = "0.9.2"
+
+    # Files that should exist in the research mission
+    REQUIRED_FILES = [
+        ("templates", "task-prompt-template.md"),
+        ("command-templates", "tasks.md"),
+    ]
+
+    def detect(self, project_path: Path) -> bool:
+        """Check if research mission is missing required templates."""
+        research_mission = project_path / ".kittify" / "missions" / "research"
+
+        if not research_mission.exists():
+            return False  # No research mission, nothing to fix
+
+        for subdir, filename in self.REQUIRED_FILES:
+            target = research_mission / subdir / filename
+            if not target.exists():
+                return True
+
+        return False
+
+    def can_apply(self, project_path: Path) -> tuple[bool, str]:
+        """Check if we can copy templates from the package."""
+        package_research = self._find_package_research_mission()
+        if package_research is None:
+            return (
+                False,
+                "Could not locate package research mission to copy templates from. "
+                "This is expected in test environments. "
+                "Run 'spec-kitty init --force' to repair missions manually.",
+            )
+
+        # Check that package has the required files
+        missing_in_pkg = []
+        for subdir, filename in self.REQUIRED_FILES:
+            src = package_research / subdir / filename
+            if not src.exists():
+                missing_in_pkg.append(f"{subdir}/{filename}")
+
+        if missing_in_pkg:
+            return (
+                False,
+                f"Package research mission is missing: {', '.join(missing_in_pkg)}. "
+                "Please upgrade spec-kitty-cli to the latest version.",
+            )
+
+        return True, ""
+
+    def apply(self, project_path: Path, dry_run: bool = False) -> MigrationResult:
+        """Copy missing templates from the package."""
+        changes: list[str] = []
+        warnings: list[str] = []
+        errors: list[str] = []
+
+        research_mission = project_path / ".kittify" / "missions" / "research"
+        package_research = self._find_package_research_mission()
+
+        if package_research is None:
+            errors.append("Could not locate package research mission")
+            return MigrationResult(success=False, errors=errors)
+
+        if not research_mission.exists():
+            # No research mission in project, nothing to do
+            return MigrationResult(
+                success=True,
+                changes_made=["Research mission not present, skipping"],
+            )
+
+        # Copy missing files
+        for subdir, filename in self.REQUIRED_FILES:
+            src = package_research / subdir / filename
+            dest_dir = research_mission / subdir
+            dest = dest_dir / filename
+
+            if dest.exists():
+                continue  # Already exists
+
+            if dry_run:
+                changes.append(f"Would add research/{subdir}/{filename}")
+            else:
+                try:
+                    # Ensure directory exists
+                    dest_dir.mkdir(parents=True, exist_ok=True)
+                    shutil.copy2(src, dest)
+                    changes.append(f"Added research/{subdir}/{filename}")
+                except OSError as e:
+                    errors.append(f"Failed to copy {subdir}/{filename}: {e}")
+
+        # Also update worktrees
+        worktrees_dir = project_path / ".worktrees"
+        if worktrees_dir.exists():
+            for worktree in worktrees_dir.iterdir():
+                if not worktree.is_dir():
+                    continue
+
+                wt_research = worktree / ".kittify" / "missions" / "research"
+                if not wt_research.exists():
+                    continue
+
+                for subdir, filename in self.REQUIRED_FILES:
+                    src = package_research / subdir / filename
+                    dest_dir = wt_research / subdir
+                    dest = dest_dir / filename
+
+                    if dest.exists():
+                        continue
+
+                    if dry_run:
+                        changes.append(
+                            f"Would add research/{subdir}/{filename} to worktree {worktree.name}"
+                        )
+                    else:
+                        try:
+                            dest_dir.mkdir(parents=True, exist_ok=True)
+                            shutil.copy2(src, dest)
+                            changes.append(
+                                f"Added research/{subdir}/{filename} to worktree {worktree.name}"
+                            )
+                        except OSError as e:
+                            warnings.append(
+                                f"Could not copy to worktree {worktree.name}: {e}"
+                            )
+
+        success = len(errors) == 0
+        return MigrationResult(
+            success=success,
+            changes_made=changes,
+            errors=errors,
+            warnings=warnings,
+        )
+
+    def _find_package_research_mission(self) -> Path | None:
+        """Find the research mission directory in the installed package or local repo."""
+        # First try from installed package
+        try:
+            from importlib.resources import files
+
+            pkg_files = files("specify_cli")
+            missions_path = pkg_files.joinpath("missions", "research")
+
+            # Convert to Path and check if it exists
+            missions_str = str(missions_path)
+            if Path(missions_str).exists():
+                return Path(missions_str)
+
+        except (ImportError, TypeError, AttributeError):
+            pass
+
+        # Try from package __file__ location
+        try:
+            import specify_cli
+
+            pkg_dir = Path(specify_cli.__file__).parent
+            research_dir = pkg_dir / "missions" / "research"
+            if research_dir.exists():
+                return research_dir
+        except (ImportError, AttributeError):
+            pass
+
+        # Fallback for development: Check SPEC_KITTY_TEMPLATE_ROOT env var
+        import os
+
+        template_root = os.environ.get("SPEC_KITTY_TEMPLATE_ROOT")
+        if template_root:
+            research_dir = Path(template_root) / ".kittify" / "missions" / "research"
+            if research_dir.exists():
+                return research_dir
+
+        # Fallback: Try to find the spec-kitty repo root
+        try:
+            cwd = Path.cwd()
+            for parent in [cwd] + list(cwd.parents):
+                research_dir = parent / "src" / "specify_cli" / "missions" / "research"
+                pyproject = parent / "pyproject.toml"
+                if research_dir.exists() and pyproject.exists():
+                    try:
+                        content = pyproject.read_text(encoding="utf-8-sig")
+                        if "spec-kitty-cli" in content:
+                            return research_dir
+                    except OSError:
+                        pass
+        except OSError:
+            pass
+
+        return None

specify_cli/upgrade/registry.py

@@ -0,0 +1,121 @@
+"""Migration registry for Spec Kitty upgrade system."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Dict, List, Type
+
+from packaging.version import Version
+
+if TYPE_CHECKING:
+    from .migrations.base import BaseMigration
+
+
+class MigrationRegistry:
+    """Registry of all available migrations, ordered by target version."""
+
+    _migrations: Dict[str, Type["BaseMigration"]] = {}
+
+    # Required fields for all migrations
+    REQUIRED_FIELDS = ['migration_id', 'description', 'target_version']
+
+    @classmethod
+    def register(
+        cls, migration_class: Type["BaseMigration"]
+    ) -> Type["BaseMigration"]:
+        """Decorator to register a migration class.
+
+        Args:
+            migration_class: The migration class to register
+
+        Returns:
+            The same migration class (for decorator use)
+
+        Raises:
+            ValueError: If migration_id is not set, required fields are missing,
+                        or a migration with this ID is already registered
+        """
+        # Validate required fields
+        for field in cls.REQUIRED_FIELDS:
+            value = getattr(migration_class, field, None)
+            if not value:
+                raise ValueError(
+                    f"Migration {migration_class.__name__} is missing required field '{field}'"
+                )
+
+        migration_id = migration_class.migration_id
+
+        # Check for duplicate registration
+        if migration_id in cls._migrations:
+            existing = cls._migrations[migration_id]
+            raise ValueError(
+                f"Duplicate migration ID '{migration_id}'. "
+                f"Already registered by {existing.__name__}, "
+                f"cannot register {migration_class.__name__}"
+            )
+
+        cls._migrations[migration_id] = migration_class
+        return migration_class
+
+    @classmethod
+    def get_all(cls) -> List["BaseMigration"]:
+        """Get all migrations as instances, ordered by target version.
+
+        Returns:
+            List of migration instances sorted by target version
+        """
+        instances = [m() for m in cls._migrations.values()]
+        return sorted(instances, key=lambda m: Version(m.target_version))
+
+    @classmethod
+    def get_applicable(
+        cls, from_version: str, to_version: str, project_path: "Path | None" = None
+    ) -> List["BaseMigration"]:
+        """Get migrations needed to go from one version to another.
+
+        Args:
+            from_version: Current version
+            to_version: Target version
+            project_path: Optional project path for detect() check
+
+        Returns:
+            List of applicable migrations in order
+        """
+        from pathlib import Path
+        from_v = Version(from_version)
+        to_v = Version(to_version)
+
+        applicable = []
+        for migration in cls.get_all():
+            target = Version(migration.target_version)
+            # Include if target is > from_version AND <= to_version
+            if from_v < target <= to_v:
+                applicable.append(migration)
+            # ALSO include migrations at current version if detect() returns True
+            elif target == from_v and project_path is not None:
+                if migration.detect(Path(project_path) if isinstance(project_path, str) else project_path):
+                    applicable.append(migration)
+
+        return applicable
+
+    @classmethod
+    def get_by_id(cls, migration_id: str) -> "BaseMigration | None":
+        """Get a specific migration by ID.
+
+        Args:
+            migration_id: The migration ID to look up
+
+        Returns:
+            Migration instance if found, None otherwise
+        """
+        migration_class = cls._migrations.get(migration_id)
+        return migration_class() if migration_class else None
+
+    @classmethod
+    def clear(cls) -> None:
+        """Clear all registered migrations (for testing)."""
+        cls._migrations.clear()
+
+
+# Export standalone decorator for convenience
+# This allows: from specify_cli.upgrade.registry import register
+register = MigrationRegistry.register

specify_cli/upgrade/runner.py

@@ -0,0 +1,284 @@
+"""Migration runner for Spec Kitty upgrade system."""
+
+from __future__ import annotations
+
+import platform
+import sys
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+from typing import List, Optional
+
+from rich.console import Console
+
+from .detector import VersionDetector
+from .metadata import ProjectMetadata
+from .migrations.base import BaseMigration, MigrationResult
+from .registry import MigrationRegistry
+
+
+@dataclass
+class UpgradeResult:
+    """Result of an upgrade operation."""
+
+    success: bool
+    from_version: str
+    to_version: str
+    migrations_applied: List[str] = field(default_factory=list)
+    migrations_skipped: List[str] = field(default_factory=list)
+    errors: List[str] = field(default_factory=list)
+    warnings: List[str] = field(default_factory=list)
+    dry_run: bool = False
+
+
+class MigrationRunner:
+    """Orchestrates the migration process."""
+
+    def __init__(self, project_path: Path, console: Optional[Console] = None):
+        """Initialize the runner.
+
+        Args:
+            project_path: Root of the project
+            console: Optional Rich console for output
+        """
+        self.project_path = project_path
+        self.kittify_dir = project_path / ".kittify"
+        self.console = console or Console()
+        self.detector = VersionDetector(project_path)
+
+    def upgrade(
+        self,
+        target_version: str,
+        dry_run: bool = False,
+        force: bool = False,
+        include_worktrees: bool = True,
+    ) -> UpgradeResult:
+        """Run all needed migrations to reach target version.
+
+        Args:
+            target_version: Version to upgrade to
+            dry_run: If True, simulate but don't apply
+            force: If True, skip confirmation prompts
+            include_worktrees: If True, also upgrade worktrees
+
+        Returns:
+            UpgradeResult with details of the upgrade
+        """
+        from_version = self.detector.detect_version()
+
+        result = UpgradeResult(
+            success=True,
+            from_version=from_version,
+            to_version=target_version,
+            dry_run=dry_run,
+        )
+
+        # Get applicable migrations
+        migrations = MigrationRegistry.get_applicable(from_version, target_version, project_path=self.project_path)
+
+        if not migrations:
+            result.warnings.append(
+                f"No migrations needed from {from_version} to {target_version}"
+            )
+            return result
+
+        # Load or create metadata
+        metadata = ProjectMetadata.load(self.kittify_dir)
+        if metadata is None:
+            metadata = self._create_initial_metadata(from_version)
+
+        # Apply each migration to main project
+        for migration in migrations:
+            migration_result = self._apply_migration(migration, metadata, dry_run)
+
+            if migration_result.success:
+                result.migrations_applied.append(migration.migration_id)
+                result.warnings.extend(migration_result.warnings)
+            else:
+                # Check if it was skipped (already applied)
+                if metadata.has_migration(migration.migration_id):
+                    result.migrations_skipped.append(migration.migration_id)
+                else:
+                    result.success = False
+                    result.errors.extend(migration_result.errors)
+                    # Stop on first failure
+                    break
+
+        # Update and save metadata for main project
+        if not dry_run and result.success:
+            metadata.version = target_version
+            metadata.last_upgraded_at = datetime.now()
+            metadata.save(self.kittify_dir)
+
+        # Handle worktrees
+        if include_worktrees:
+            worktrees_result = self._upgrade_worktrees(
+                target_version, migrations, dry_run
+            )
+            result.warnings.extend(worktrees_result.get("warnings", []))
+            if worktrees_result.get("errors"):
+                result.errors.extend(worktrees_result["errors"])
+                # Don't fail the whole upgrade for worktree issues
+                result.warnings.append(
+                    "Some worktrees had issues - check errors above"
+                )
+
+        return result
+
+    def _apply_migration(
+        self,
+        migration: BaseMigration,
+        metadata: ProjectMetadata,
+        dry_run: bool,
+    ) -> MigrationResult:
+        """Apply a single migration.
+
+        Args:
+            migration: The migration to apply
+            metadata: Project metadata
+            dry_run: Whether to simulate only
+
+        Returns:
+            MigrationResult with details
+        """
+        # Skip if already applied
+        if metadata.has_migration(migration.migration_id):
+            return MigrationResult(
+                success=True,
+                warnings=[f"Migration {migration.migration_id} already applied, skipping"],
+            )
+
+        # Check if migration is needed via detection
+        if not migration.detect(self.project_path):
+            # Migration not needed - project doesn't have old state
+            if not dry_run:
+                metadata.record_migration(
+                    migration.migration_id, "skipped", "Not applicable"
+                )
+            return MigrationResult(
+                success=True,
+                warnings=[
+                    f"Migration {migration.migration_id} not needed (project already in target state)"
+                ],
+            )
+
+        # Check if safe to apply
+        can_apply, reason = migration.can_apply(self.project_path)
+        if not can_apply:
+            return MigrationResult(
+                success=False,
+                errors=[f"Cannot apply {migration.migration_id}: {reason}"],
+            )
+
+        # Apply the migration
+        result = migration.apply(self.project_path, dry_run=dry_run)
+
+        # Record in metadata
+        if not dry_run:
+            metadata.record_migration(
+                migration.migration_id,
+                "success" if result.success else "failed",
+                "; ".join(result.changes_made) if result.changes_made else None,
+            )
+
+        return result
+
+    def _upgrade_worktrees(
+        self,
+        target_version: str,
+        migrations: List[BaseMigration],
+        dry_run: bool,
+    ) -> dict:
+        """Upgrade all worktrees in .worktrees/ directory.
+
+        Args:
+            target_version: Target version
+            migrations: List of migrations to apply
+            dry_run: Whether to simulate only
+
+        Returns:
+            Dict with warnings and errors lists
+        """
+        result: dict = {"warnings": [], "errors": []}
+
+        worktrees_dir = self.project_path / ".worktrees"
+        if not worktrees_dir.exists():
+            return result
+
+        for worktree in worktrees_dir.iterdir():
+            if not worktree.is_dir():
+                continue
+
+            wt_kittify = worktree / ".kittify"
+            if not wt_kittify.exists():
+                continue
+
+            # Load or create worktree metadata
+            wt_metadata = ProjectMetadata.load(wt_kittify)
+            if wt_metadata is None:
+                wt_detector = VersionDetector(worktree)
+                wt_version = wt_detector.detect_version()
+                wt_metadata = self._create_initial_metadata(wt_version)
+
+            # Apply migrations to worktree
+            for migration in migrations:
+                if wt_metadata.has_migration(migration.migration_id):
+                    continue
+
+                if not migration.detect(worktree):
+                    if not dry_run:
+                        wt_metadata.record_migration(
+                            migration.migration_id, "skipped", "Not applicable"
+                        )
+                    continue
+
+                can_apply, reason = migration.can_apply(worktree)
+                if not can_apply:
+                    result["warnings"].append(
+                        f"Worktree {worktree.name}: Cannot apply {migration.migration_id}: {reason}"
+                    )
+                    continue
+
+                migration_result = migration.apply(worktree, dry_run=dry_run)
+
+                if migration_result.success:
+                    if not dry_run:
+                        wt_metadata.record_migration(
+                            migration.migration_id,
+                            "success",
+                            "; ".join(migration_result.changes_made)
+                            if migration_result.changes_made
+                            else None,
+                        )
+                    result["warnings"].extend(
+                        [f"Worktree {worktree.name}: {w}" for w in migration_result.warnings]
+                    )
+                else:
+                    result["errors"].extend(
+                        [f"Worktree {worktree.name}: {e}" for e in migration_result.errors]
+                    )
+
+            # Save worktree metadata
+            if not dry_run:
+                wt_metadata.version = target_version
+                wt_metadata.last_upgraded_at = datetime.now()
+                wt_metadata.save(wt_kittify)
+
+        return result
+
+    def _create_initial_metadata(self, detected_version: str) -> ProjectMetadata:
+        """Create initial metadata for a project without it.
+
+        Args:
+            detected_version: Version detected from heuristics
+
+        Returns:
+            New ProjectMetadata instance
+        """
+        return ProjectMetadata(
+            version=detected_version,
+            initialized_at=datetime.now(),
+            python_version=platform.python_version(),
+            platform=sys.platform,
+            platform_version=platform.platform(),
+        )

specify_cli/validators/__init__.py

@@ -0,0 +1,14 @@
+"""Validation helpers for Spec Kitty missions.
+
+This package hosts mission-specific validators that keep artifacts such
+as CSV trackers and path conventions consistent. Modules included:
+
+- ``research`` – citation + bibliography validation for research mission
+- ``paths`` – (placeholder) path convention validation shared by missions
+"""
+
+from __future__ import annotations
+
+from . import paths, research
+
+__all__ = ["paths", "research"]