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

specify_cli/upgrade/migrations/m_0_7_3_update_scripts.py

@@ -0,0 +1,114 @@
+"""Migration: Update scripts to latest version."""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+from ..registry import MigrationRegistry
+from .base import BaseMigration, MigrationResult
+
+
+@MigrationRegistry.register
+class UpdateScriptsMigration(BaseMigration):
+    """Update .kittify/scripts/ to latest version.
+
+    The create-new-feature.sh script was fixed in v0.7.3 to scan both
+    kitty-specs/ AND .worktrees/ for existing feature numbers. Projects
+    initialized before v0.7.3 have the old script that only scans kitty-specs/,
+    causing duplicate feature numbers when using worktrees.
+    """
+
+    migration_id = "0.7.3_update_scripts"
+    description = "Update scripts to fix worktree feature numbering"
+    target_version = "0.7.3"
+
+    def detect(self, project_path: Path) -> bool:
+        """Check if project has old scripts that need updating."""
+        script_path = project_path / ".kittify" / "scripts" / "bash" / "create-new-feature.sh"
+
+        if not script_path.exists():
+            return False
+
+        # Check if script has the fix (scans .worktrees/)
+        try:
+            content = script_path.read_text(encoding="utf-8")
+            # Old script doesn't have this line
+            if "Also scan .worktrees/" not in content:
+                return True
+        except (OSError, UnicodeDecodeError):
+            return False
+
+        return False
+
+    def can_apply(self, project_path: Path) -> tuple[bool, str]:
+        """Check if we can apply this migration."""
+        kittify_dir = project_path / ".kittify"
+        if not kittify_dir.exists():
+            return False, "No .kittify directory (not a spec-kitty project)"
+
+        return True, ""
+
+    def apply(self, project_path: Path, dry_run: bool = False) -> MigrationResult:
+        """Copy updated scripts from package templates."""
+        changes: list[str] = []
+        warnings: list[str] = []
+        errors: list[str] = []
+
+        import specify_cli
+
+        pkg_root = Path(specify_cli.__file__).parent
+
+        # Scripts to update
+        scripts = [
+            ("scripts/bash/create-new-feature.sh", ".kittify/scripts/bash/create-new-feature.sh"),
+            ("scripts/bash/common.sh", ".kittify/scripts/bash/common.sh"),
+        ]
+
+        any_scripts_found = False
+        for src_rel, _ in scripts:
+            if (pkg_root / src_rel).exists():
+                any_scripts_found = True
+                break
+
+        if not any_scripts_found:
+            warnings.append(
+                "Bash scripts not found in package (removed in later version or never existed). "
+                "If you need script updates, they may have been handled by migration 0.10.0 cleanup. "
+                "This is not an error."
+            )
+            return MigrationResult(
+                success=True,
+                changes_made=[],
+                errors=[],
+                warnings=warnings,
+            )
+
+        for src_rel, dest_rel in scripts:
+            src = pkg_root / src_rel
+            dest = project_path / dest_rel
+
+            if not src.exists():
+                warnings.append(f"Template {src_rel} not found in package")
+                continue
+
+            if not dest.parent.exists():
+                if not dry_run:
+                    dest.parent.mkdir(parents=True, exist_ok=True)
+
+            if dry_run:
+                changes.append(f"Would update {dest_rel}")
+            else:
+                try:
+                    shutil.copy2(src, dest)
+                    changes.append(f"Updated {dest_rel}")
+                except OSError as e:
+                    errors.append(f"Failed to update {dest_rel}: {e}")
+
+        success = len(errors) == 0
+        return MigrationResult(
+            success=success,
+            changes_made=changes,
+            errors=errors,
+            warnings=warnings,
+        )

specify_cli/upgrade/migrations/m_0_8_0_remove_active_mission.py

@@ -0,0 +1,82 @@
+"""Migration: Remove deprecated .kittify/active-mission file/symlink."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..registry import MigrationRegistry
+from .base import BaseMigration, MigrationResult
+
+
+@MigrationRegistry.register
+class RemoveActiveMissionMigration(BaseMigration):
+    """Remove deprecated .kittify/active-mission file or symlink.
+
+    As of v0.8.0, missions are selected per-feature during /spec-kitty.specify.
+    The project-level .kittify/active-mission symlink/file is no longer used.
+
+    This migration removes the obsolete active-mission file and informs the
+    user about the new per-feature mission workflow.
+    """
+
+    migration_id = "0.8.0_remove_active_mission"
+    description = "Remove deprecated .kittify/active-mission (missions are now per-feature)"
+    target_version = "0.8.0"
+
+    def detect(self, project_path: Path) -> bool:
+        """Check if .kittify/active-mission exists."""
+        kittify_dir = project_path / ".kittify"
+        active_mission = kittify_dir / "active-mission"
+
+        # Check for file, symlink, or broken symlink
+        return active_mission.exists() or active_mission.is_symlink()
+
+    def can_apply(self, project_path: Path) -> tuple[bool, str]:
+        """Migration can always be applied if active-mission exists."""
+        return True, ""
+
+    def apply(self, project_path: Path, dry_run: bool = False) -> MigrationResult:
+        """Remove .kittify/active-mission file or symlink."""
+        changes: list[str] = []
+        warnings: list[str] = []
+        errors: list[str] = []
+
+        kittify_dir = project_path / ".kittify"
+        active_mission = kittify_dir / "active-mission"
+
+        if active_mission.exists() or active_mission.is_symlink():
+            if dry_run:
+                changes.append(
+                    "Would remove .kittify/active-mission"
+                )
+                changes.append(
+                    "  -> Missions are now selected per-feature during /spec-kitty.specify"
+                )
+            else:
+                try:
+                    active_mission.unlink()
+                    changes.append(
+                        "Removed deprecated .kittify/active-mission"
+                    )
+                    changes.append(
+                        "  -> Missions are now selected per-feature during /spec-kitty.specify"
+                    )
+                    changes.append(
+                        "  -> Existing features will use 'software-dev' mission by default"
+                    )
+                except OSError as e:
+                    errors.append(
+                        f"Failed to remove .kittify/active-mission: {e}"
+                    )
+        else:
+            warnings.append(
+                "No .kittify/active-mission found (already migrated or new project)"
+            )
+
+        success = len(errors) == 0
+        return MigrationResult(
+            success=success,
+            changes_made=changes,
+            errors=errors,
+            warnings=warnings,
+        )

specify_cli/upgrade/migrations/m_0_8_0_worktree_agents_symlink.py

@@ -0,0 +1,148 @@
+"""Migration: Create AGENTS.md symlink in worktrees."""
+
+from __future__ import annotations
+
+import os
+import shutil
+from pathlib import Path
+
+from ..registry import MigrationRegistry
+from .base import BaseMigration, MigrationResult
+
+
+@MigrationRegistry.register
+class WorktreeAgentsSymlinkMigration(BaseMigration):
+    """Create .kittify/AGENTS.md symlink in worktrees.
+
+    Worktrees need access to the main repo's .kittify/AGENTS.md file
+    for command templates that reference it. Since .kittify/ is gitignored,
+    worktrees don't automatically have it.
+
+    This migration creates a symlink from each worktree's
+    .kittify/AGENTS.md to the main repo's .kittify/AGENTS.md.
+    """
+
+    migration_id = "0.8.0_worktree_agents_symlink"
+    description = "Create .kittify/AGENTS.md symlink in worktrees"
+    target_version = "0.8.0"
+
+    def detect(self, project_path: Path) -> bool:
+        """Check if any worktrees are missing .kittify/AGENTS.md."""
+        worktrees_dir = project_path / ".worktrees"
+        main_agents = project_path / ".kittify" / "AGENTS.md"
+
+        # No main AGENTS.md means nothing to symlink
+        if not main_agents.exists():
+            return False
+
+        if not worktrees_dir.exists():
+            return False
+
+        for worktree in worktrees_dir.iterdir():
+            if worktree.is_dir() and not worktree.name.startswith('.'):
+                wt_agents = worktree / ".kittify" / "AGENTS.md"
+                # Check if missing or broken symlink
+                if not wt_agents.exists() and not wt_agents.is_symlink():
+                    return True
+                # Also check for broken symlinks
+                if wt_agents.is_symlink() and not wt_agents.exists():
+                    return True
+
+        return False
+
+    def can_apply(self, project_path: Path) -> tuple[bool, str]:
+        """Check that main repo has AGENTS.md."""
+        main_agents = project_path / ".kittify" / "AGENTS.md"
+
+        if not main_agents.exists():
+            return (
+                False,
+                "Main repo .kittify/AGENTS.md must exist before creating symlinks"
+            )
+
+        return True, ""
+
+    def apply(self, project_path: Path, dry_run: bool = False) -> MigrationResult:
+        """Create .kittify/AGENTS.md symlink in all worktrees."""
+        changes: list[str] = []
+        warnings: list[str] = []
+        errors: list[str] = []
+
+        worktrees_dir = project_path / ".worktrees"
+        main_agents = project_path / ".kittify" / "AGENTS.md"
+
+        if not main_agents.exists():
+            warnings.append("Main repo .kittify/AGENTS.md not found, skipping")
+            return MigrationResult(
+                success=True,
+                changes_made=changes,
+                errors=errors,
+                warnings=warnings,
+            )
+
+        if worktrees_dir.exists():
+            for worktree in worktrees_dir.iterdir():
+                if worktree.is_dir() and not worktree.name.startswith('.'):
+                    wt_kittify = worktree / ".kittify"
+                    wt_agents = wt_kittify / "AGENTS.md"
+
+                    # Skip if already exists and is valid
+                    if wt_agents.exists() and not wt_agents.is_symlink():
+                        warnings.append(
+                            f"Worktree {worktree.name} has non-symlink AGENTS.md, skipping"
+                        )
+                        continue
+
+                    if wt_agents.is_symlink() and wt_agents.exists():
+                        # Valid symlink already exists
+                        continue
+
+                    # Calculate relative path: ../../../.kittify/AGENTS.md
+                    # From: .worktrees/001-feature/.kittify/AGENTS.md
+                    # To:   .kittify/AGENTS.md
+                    relative_path = "../../../.kittify/AGENTS.md"
+
+                    if dry_run:
+                        changes.append(
+                            f"Would create .kittify/AGENTS.md symlink in worktree {worktree.name}"
+                        )
+                    else:
+                        try:
+                            # Ensure .kittify directory exists
+                            wt_kittify.mkdir(parents=True, exist_ok=True)
+
+                            # Remove broken symlink if present
+                            if wt_agents.is_symlink():
+                                wt_agents.unlink()
+
+                            # Create the symlink
+                            # Need to change to the directory to create relative symlink
+                            original_cwd = os.getcwd()
+                            try:
+                                os.chdir(wt_kittify)
+                                os.symlink(relative_path, "AGENTS.md")
+                            finally:
+                                os.chdir(original_cwd)
+
+                            changes.append(
+                                f"Created .kittify/AGENTS.md symlink in worktree {worktree.name}"
+                            )
+                        except OSError as e:
+                            # Symlink failed (Windows?), try copying instead
+                            try:
+                                shutil.copy2(main_agents, wt_agents)
+                                changes.append(
+                                    f"Copied .kittify/AGENTS.md to worktree {worktree.name} (symlink failed)"
+                                )
+                            except OSError as copy_error:
+                                errors.append(
+                                    f"Failed to create AGENTS.md in {worktree.name}: {e}, copy also failed: {copy_error}"
+                                )
+
+        success = len(errors) == 0
+        return MigrationResult(
+            success=success,
+            changes_made=changes,
+            errors=errors,
+            warnings=warnings,
+        )

specify_cli/upgrade/migrations/m_0_9_0_frontmatter_only_lanes.py

@@ -0,0 +1,346 @@
+"""Migration: Convert directory-based task lanes to frontmatter-only lanes."""
+
+from __future__ import annotations
+
+import re
+import shutil
+from pathlib import Path
+from typing import List, Tuple
+
+from ..registry import MigrationRegistry
+from .base import BaseMigration, MigrationResult
+
+
+@MigrationRegistry.register
+class FrontmatterOnlyLanesMigration(BaseMigration):
+    """Migrate from directory-based to frontmatter-only lane management.
+
+    As of v0.9.0, task lanes are determined solely by the `lane:` field
+    in the YAML frontmatter of work package files. The directory structure
+    (tasks/planned/, tasks/doing/, etc.) is flattened to a single tasks/
+    directory.
+
+    This migration:
+    1. Moves WP files from tasks/{lane}/ to tasks/
+    2. Ensures the `lane:` field is set from the source directory
+    3. Removes empty lane subdirectories
+    4. Processes main kitty-specs/ and all .worktrees/
+    """
+
+    migration_id = "0.9.0_frontmatter_only_lanes"
+    description = "Flatten task lanes to frontmatter-only (no more directory-based lanes)"
+    target_version = "0.9.0"
+
+    LANE_DIRS: Tuple[str, ...] = ("planned", "doing", "for_review", "done")
+
+    # System files to ignore when determining if a directory is empty
+    # These files are created automatically by operating systems and should not
+    # prevent lane directory cleanup
+    IGNORE_FILES = frozenset({
+        ".gitkeep",      # Git placeholder
+        ".DS_Store",     # macOS Finder metadata
+        "Thumbs.db",     # Windows thumbnail cache
+        "desktop.ini",   # Windows folder settings
+        ".directory",    # KDE folder settings
+        "._*",           # macOS resource fork prefix (pattern)
+    })
+
+    @classmethod
+    def _should_ignore_file(cls, filename: str) -> bool:
+        """Check if a file should be ignored when determining if directory is empty.
+
+        Args:
+            filename: Name of the file to check
+
+        Returns:
+            True if file should be ignored (system file), False otherwise
+        """
+        # Check exact matches
+        if filename in cls.IGNORE_FILES:
+            return True
+
+        # Check pattern matches (e.g., ._* for macOS resource forks)
+        # Check for macOS resource fork files (._filename)
+        if filename.startswith("._"):
+            return True
+
+        return False
+
+    @classmethod
+    def _get_real_contents(cls, directory: Path) -> List[Path]:
+        """Get directory contents, excluding system files.
+
+        Args:
+            directory: Path to directory to check
+
+        Returns:
+            List of "real" files (excluding system files like .DS_Store)
+        """
+        if not directory.exists() or not directory.is_dir():
+            return []
+
+        return [
+            item
+            for item in directory.iterdir()
+            if not cls._should_ignore_file(item.name)
+        ]
+
+    def detect(self, project_path: Path) -> bool:
+        """Check if any feature uses legacy directory-based lanes."""
+        # Check main kitty-specs/
+        main_specs = project_path / "kitty-specs"
+        if main_specs.exists():
+            for feature_dir in main_specs.iterdir():
+                if feature_dir.is_dir() and self._is_legacy_format(feature_dir):
+                    return True
+
+        # Check .worktrees/
+        worktrees_dir = project_path / ".worktrees"
+        if worktrees_dir.exists():
+            for worktree in worktrees_dir.iterdir():
+                if worktree.is_dir():
+                    wt_specs = worktree / "kitty-specs"
+                    if wt_specs.exists():
+                        for feature_dir in wt_specs.iterdir():
+                            if feature_dir.is_dir() and self._is_legacy_format(feature_dir):
+                                return True
+
+        return False
+
+    def _is_legacy_format(self, feature_path: Path) -> bool:
+        """Check if a feature uses legacy directory-based lanes."""
+        tasks_dir = feature_path / "tasks"
+        if not tasks_dir.exists():
+            return False
+
+        # A feature is legacy if it has ANY lane subdirectories
+        # (even if empty - they shouldn't exist in new format)
+        for lane in self.LANE_DIRS:
+            lane_path = tasks_dir / lane
+            if lane_path.exists() and lane_path.is_dir():
+                # Directory exists - this is legacy format
+                # Check if it has any real content (ignoring system files)
+                real_contents = self._get_real_contents(lane_path)
+                if real_contents:
+                    return True
+                # Even if only system files, still need migration to remove the directory
+                # (The directory itself shouldn't exist in new format)
+                elif any(lane_path.iterdir()):
+                    return True
+
+        return False
+
+    def can_apply(self, project_path: Path) -> tuple[bool, str]:
+        """Migration can always be applied if legacy format is detected."""
+        return True, ""
+
+    def apply(self, project_path: Path, dry_run: bool = False) -> MigrationResult:
+        """Migrate all features from directory-based to frontmatter-only lanes."""
+        changes: List[str] = []
+        warnings: List[str] = []
+        errors: List[str] = []
+
+        features_found = self._find_features_to_migrate(project_path)
+
+        if not features_found:
+            warnings.append("No features need migration - all already use flat structure")
+            return MigrationResult(
+                success=True,
+                changes_made=changes,
+                errors=errors,
+                warnings=warnings,
+            )
+
+        total_migrated = 0
+        total_skipped = 0
+
+        for feature_dir, location_label in features_found:
+            feature_changes, feature_warnings, feature_errors, migrated, skipped = (
+                self._migrate_feature(feature_dir, location_label, dry_run)
+            )
+            changes.extend(feature_changes)
+            warnings.extend(feature_warnings)
+            errors.extend(feature_errors)
+            total_migrated += migrated
+            total_skipped += skipped
+
+        if dry_run:
+            changes.append(f"Would migrate {total_migrated} WP files across {len(features_found)} features")
+        else:
+            changes.append(f"Migrated {total_migrated} WP files across {len(features_found)} features")
+
+        if total_skipped > 0:
+            warnings.append(f"Skipped {total_skipped} files (already exist or conflicts)")
+
+        success = len(errors) == 0
+        return MigrationResult(
+            success=success,
+            changes_made=changes,
+            errors=errors,
+            warnings=warnings,
+        )
+
+    def _find_features_to_migrate(self, project_path: Path) -> List[Tuple[Path, str]]:
+        """Find all features with legacy format in main repo and worktrees."""
+        features: List[Tuple[Path, str]] = []
+
+        # Scan main kitty-specs/
+        main_specs = project_path / "kitty-specs"
+        if main_specs.exists():
+            for feature_dir in sorted(main_specs.iterdir()):
+                if feature_dir.is_dir() and self._is_legacy_format(feature_dir):
+                    features.append((feature_dir, "main"))
+
+        # Scan .worktrees/
+        worktrees_dir = project_path / ".worktrees"
+        if worktrees_dir.exists():
+            for worktree in sorted(worktrees_dir.iterdir()):
+                if worktree.is_dir():
+                    wt_specs = worktree / "kitty-specs"
+                    if wt_specs.exists():
+                        for feature_dir in sorted(wt_specs.iterdir()):
+                            if feature_dir.is_dir() and self._is_legacy_format(feature_dir):
+                                features.append((feature_dir, f"worktree:{worktree.name}"))
+
+        return features
+
+    def _migrate_feature(
+        self,
+        feature_dir: Path,
+        location_label: str,
+        dry_run: bool,
+    ) -> Tuple[List[str], List[str], List[str], int, int]:
+        """Migrate a single feature from directory-based to flat structure."""
+        changes: List[str] = []
+        warnings: List[str] = []
+        errors: List[str] = []
+        migrated = 0
+        skipped = 0
+
+        tasks_dir = feature_dir / "tasks"
+        if not tasks_dir.exists():
+            return changes, warnings, errors, migrated, skipped
+
+        feature_name = feature_dir.name
+        changes.append(f"[{location_label}] {feature_name}:")
+
+        for lane in self.LANE_DIRS:
+            lane_dir = tasks_dir / lane
+            if not lane_dir.is_dir():
+                continue
+
+            # Find ALL markdown files, not just WP*.md
+            md_files = sorted(lane_dir.glob("*.md"))
+
+            for md_file in md_files:
+                # Skip README.md if it exists
+                if md_file.name == "README.md":
+                    continue
+
+                target = tasks_dir / md_file.name
+
+                # Check if already exists in flat directory
+                if target.exists():
+                    warnings.append(f"  Skip: {md_file.name} already exists in tasks/")
+                    skipped += 1
+                    continue
+
+                try:
+                    if dry_run:
+                        changes.append(f"  Would move: {lane}/{md_file.name} → tasks/{md_file.name}")
+                    else:
+                        # Read and update content
+                        content = md_file.read_text(encoding="utf-8-sig")
+                        updated_content = self._ensure_lane_in_frontmatter(content, lane)
+
+                        # Write to new location
+                        target.write_text(updated_content, encoding="utf-8")
+
+                        # Remove original
+                        md_file.unlink()
+
+                        changes.append(f"  Moved: {lane}/{md_file.name} → tasks/{md_file.name}")
+
+                    migrated += 1
+
+                except Exception as e:
+                    errors.append(f"  Error migrating {md_file.name}: {e}")
+
+        # Clean up empty lane directories
+        if not dry_run:
+            for lane in self.LANE_DIRS:
+                lane_dir = tasks_dir / lane
+                if lane_dir.exists() and lane_dir.is_dir():
+                    # Check for real contents (ignoring system files)
+                    real_contents = self._get_real_contents(lane_dir)
+                    if not real_contents:
+                        # Directory has no real files (only system files like .DS_Store or .gitkeep)
+                        try:
+                            # Use shutil.rmtree for more robust removal
+                            # This will remove the directory and all system files within it
+                            shutil.rmtree(lane_dir)
+                            changes.append(f"  Removed empty: {lane}/")
+                        except OSError as e:
+                            warnings.append(f"  Could not remove {lane}/: {e}")
+        else:
+            for lane in self.LANE_DIRS:
+                lane_dir = tasks_dir / lane
+                if lane_dir.exists() and lane_dir.is_dir():
+                    real_contents = self._get_real_contents(lane_dir)
+                    if not real_contents:
+                        changes.append(f"  Would remove empty: {lane}/")
+
+        return changes, warnings, errors, migrated, skipped
+
+    def _ensure_lane_in_frontmatter(self, content: str, expected_lane: str) -> str:
+        """Ensure frontmatter has correct lane field."""
+        # Find frontmatter boundaries
+        if not content.startswith("---"):
+            # No frontmatter, add it
+            return f'---\nlane: "{expected_lane}"\n---\n{content}'
+
+        # Find closing ---
+        lines = content.split("\n")
+        closing_idx = -1
+        for i, line in enumerate(lines[1:], start=1):
+            if line.strip() == "---":
+                closing_idx = i
+                break
+
+        if closing_idx == -1:
+            # Malformed frontmatter, add lane anyway
+            return f'---\nlane: "{expected_lane}"\n---\n{content}'
+
+        frontmatter_lines = lines[1:closing_idx]
+        body_lines = lines[closing_idx + 1:]
+
+        # Check if lane field exists
+        lane_pattern = re.compile(r'^lane:\s*(.*)$')
+        lane_found = False
+        updated_lines = []
+
+        for line in frontmatter_lines:
+            match = lane_pattern.match(line)
+            if match:
+                lane_found = True
+                current_value = match.group(1).strip().strip('"\'')
+                if current_value != expected_lane:
+                    # Replace with expected lane from directory
+                    updated_lines.append(f'lane: "{expected_lane}"')
+                else:
+                    updated_lines.append(line)
+            else:
+                updated_lines.append(line)
+
+        if not lane_found:
+            # Insert lane field (before history: if present, otherwise at end)
+            insert_idx = len(updated_lines)
+            for i, line in enumerate(updated_lines):
+                if line.startswith("history:"):
+                    insert_idx = i
+                    break
+            updated_lines.insert(insert_idx, f'lane: "{expected_lane}"')
+
+        # Reconstruct document
+        result_lines = ["---"] + updated_lines + ["---"] + body_lines
+        return "\n".join(result_lines)