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

specify_cli/upgrade/migrations/m_0_11_3_workflow_agent_flag.py

@@ -0,0 +1,114 @@
+"""Migration: Ensure workflow commands in agent prompts include --agent."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import List
+
+from ..registry import MigrationRegistry
+from .base import BaseMigration, MigrationResult
+from .m_0_9_1_complete_lane_migration import get_agent_dirs_for_project
+
+
+@MigrationRegistry.register
+class WorkflowAgentFlagMigration(BaseMigration):
+    """Append --agent <name> to workflow commands in agent prompts."""
+
+    migration_id = "0.11.3_workflow_agent_flag"
+    description = "Ensure workflow commands in agent prompts include --agent"
+    target_version = "0.11.3"
+
+    AGENT_NAME_MAP = {
+        ".github": "copilot",
+        ".augment": "auggie",
+        ".amazonq": "q",
+    }
+
+    TARGET_FILES = ("spec-kitty.implement.md", "spec-kitty.review.md")
+
+    def _agent_name(self, agent_root: str) -> str:
+        return self.AGENT_NAME_MAP.get(agent_root, agent_root.lstrip("."))
+
+    def _update_workflow_lines(self, path: Path, agent_name: str, dry_run: bool) -> bool:
+        if not path.exists():
+            return False
+
+        text = path.read_text(encoding="utf-8")
+        lines = text.splitlines()
+        updated = False
+
+        def _patch_line(line: str) -> str:
+            nonlocal updated
+            # Replace __AGENT__ placeholder with actual agent name
+            if "__AGENT__" in line:
+                updated = True
+                line = line.replace("__AGENT__", agent_name)
+            # Add --agent flag if missing
+            if "spec-kitty agent workflow implement" in line and "--agent" not in line:
+                updated = True
+                return f"{line} --agent {agent_name}"
+            if "spec-kitty agent workflow review" in line and "--agent" not in line:
+                updated = True
+                return f"{line} --agent {agent_name}"
+            return line
+
+        lines = [_patch_line(line) for line in lines]
+        if updated and not dry_run:
+            path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+        return updated
+
+    def detect(self, project_path: Path) -> bool:
+        agent_dirs = get_agent_dirs_for_project(project_path)
+        for agent_root, subdir in agent_dirs:
+            agent_dir = project_path / agent_root / subdir
+            if not agent_dir.exists():
+                continue
+            agent_name = self._agent_name(agent_root)
+            for filename in self.TARGET_FILES:
+                path = agent_dir / filename
+                if not path.exists():
+                    continue
+                text = path.read_text(encoding="utf-8")
+                for line in text.splitlines():
+                    # Detect __AGENT__ placeholder that needs replacement
+                    if "__AGENT__" in line:
+                        return True
+                    if "spec-kitty agent workflow implement" in line and "--agent" not in line:
+                        return True
+                    if "spec-kitty agent workflow review" in line and "--agent" not in line:
+                        return True
+        return False
+
+    def can_apply(self, project_path: Path) -> tuple[bool, str]:
+        if not (project_path / ".kittify").exists():
+            return False, "No .kittify directory (not a spec-kitty project)"
+        return True, ""
+
+    def apply(self, project_path: Path, dry_run: bool = False) -> MigrationResult:
+        changes: List[str] = []
+        warnings: List[str] = []
+        errors: List[str] = []
+
+        agent_dirs = get_agent_dirs_for_project(project_path)
+        for agent_root, subdir in agent_dirs:
+            agent_dir = project_path / agent_root / subdir
+            if not agent_dir.exists():
+                continue
+            agent_name = self._agent_name(agent_root)
+            updated_count = 0
+            for filename in self.TARGET_FILES:
+                path = agent_dir / filename
+                if self._update_workflow_lines(path, agent_name, dry_run):
+                    updated_count += 1
+            if updated_count:
+                changes.append(f"Updated {updated_count} workflow prompts for {agent_name}")
+
+        if not changes:
+            warnings.append("No workflow prompts required updates")
+
+        return MigrationResult(
+            success=len(errors) == 0,
+            changes_made=changes,
+            errors=errors,
+            warnings=warnings,
+        )

specify_cli/upgrade/migrations/m_0_12_0_documentation_mission.py

@@ -0,0 +1,155 @@
+"""Migration: Install documentation mission to user projects (v0.12.0)."""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+from typing import Optional
+
+from ..registry import MigrationRegistry
+from .base import BaseMigration, MigrationResult
+
+
+@MigrationRegistry.register
+class InstallDocumentationMission(BaseMigration):
+    """Install the documentation mission to user projects.
+
+    This migration copies the documentation mission from the spec-kitty
+    installation (src/specify_cli/missions/documentation/) to the user's
+    project (.kittify/missions/documentation/).
+
+    The documentation mission enables users to create and maintain software
+    documentation following Write the Docs and Divio principles.
+    """
+
+    migration_id = "0.12.0_documentation_mission"
+    description = "Install documentation mission to user projects"
+    target_version = "0.12.0"
+
+    def detect(self, project_path: Path) -> bool:
+        """Detect if documentation mission needs to be installed.
+
+        Args:
+            project_path: Root directory of user's spec-kitty project
+
+        Returns:
+            True if documentation mission is missing, False if already installed
+        """
+        kittify_dir = project_path / ".kittify"
+
+        if not kittify_dir.exists():
+            # Not a spec-kitty project, migration doesn't apply
+            return False
+
+        missions_dir = kittify_dir / "missions"
+
+        if not missions_dir.exists():
+            # Missions directory doesn't exist (very old project)
+            # Migration should run to create it
+            return True
+
+        doc_mission_dir = missions_dir / "documentation"
+
+        # Check if documentation mission already exists
+        if doc_mission_dir.exists() and (doc_mission_dir / "mission.yaml").exists():
+            # Already installed
+            return False
+
+        # Documentation mission is missing, migration should run
+        return True
+
+    def can_apply(self, project_path: Path) -> tuple[bool, str]:
+        """Check if migration can be safely applied.
+
+        Args:
+            project_path: Root of the project
+
+        Returns:
+            (can_apply, reason) - True if safe, False with explanation if not
+        """
+        # Check if source mission exists
+        source_mission = self._find_source_mission()
+        if source_mission is None:
+            return (
+                False,
+                "Could not locate documentation mission source in spec-kitty installation. "
+                "This may indicate an incomplete installation.",
+            )
+
+        return True, ""
+
+    def apply(self, project_path: Path, dry_run: bool = False) -> MigrationResult:
+        """Copy documentation mission to user project.
+
+        Args:
+            project_path: Root directory of user's spec-kitty project
+            dry_run: If True, only simulate changes
+
+        Returns:
+            MigrationResult indicating success or failure
+        """
+        changes: list[str] = []
+        errors: list[str] = []
+
+        kittify_dir = project_path / ".kittify"
+        missions_dir = kittify_dir / "missions"
+
+        # Find source documentation mission
+        source_mission = self._find_source_mission()
+
+        if source_mission is None:
+            errors.append("Could not find documentation mission source in spec-kitty installation")
+            return MigrationResult(success=False, errors=errors)
+
+        # Destination
+        dest_mission = missions_dir / "documentation"
+
+        # Check if destination already exists
+        if dest_mission.exists() and (dest_mission / "mission.yaml").exists():
+            return MigrationResult(
+                success=True,
+                changes_made=["Documentation mission already installed (skipped)"]
+            )
+
+        # Ensure missions directory exists
+        if not missions_dir.exists():
+            if dry_run:
+                changes.append("Would create .kittify/missions/ directory")
+            else:
+                missions_dir.mkdir(parents=True, exist_ok=True)
+                changes.append("Created .kittify/missions/ directory")
+
+        # Copy mission directory
+        if dry_run:
+            changes.append("Would copy documentation mission to .kittify/missions/documentation/")
+        else:
+            try:
+                shutil.copytree(source_mission, dest_mission)
+
+                # Count copied files for reporting
+                copied_files = list(dest_mission.rglob("*"))
+                file_count = len([f for f in copied_files if f.is_file()])
+
+                changes.append(f"Copied documentation mission ({file_count} files)")
+
+            except Exception as e:
+                errors.append(f"Failed to copy documentation mission: {e}")
+                return MigrationResult(success=False, errors=errors)
+
+        return MigrationResult(success=True, changes_made=changes)
+
+    def _find_source_mission(self) -> Optional[Path]:
+        """Find the documentation mission in spec-kitty's installation.
+
+        Returns:
+            Path to source mission directory, or None if not found
+        """
+        # The source is relative to this migration file
+        migrations_dir = Path(__file__).parent
+        src_dir = migrations_dir.parent.parent  # Up to src/specify_cli/
+        source_mission = src_dir / "missions" / "documentation"
+
+        if source_mission.exists() and (source_mission / "mission.yaml").exists():
+            return source_mission
+
+        return None

specify_cli/upgrade/migrations/m_0_12_1_remove_kitty_specs_from_gitignore.py

@@ -0,0 +1,183 @@
+"""Migration: Remove kitty-specs/ from main repo .gitignore.
+
+Historical context:
+- Earlier spec-kitty versions or user templates may have added `kitty-specs/` to .gitignore
+- This prevents git from tracking feature specifications, causing failures in:
+  - `spec-kitty agent feature create-feature`
+  - `/spec-kitty.specify` (commit step)
+  - Other commands that commit to kitty-specs/
+
+The fix:
+- Remove `kitty-specs/` entries from main repo .gitignore
+- Keep worktree-specific patterns like `kitty-specs/**/tasks/*.md` (those prevent merge conflicts)
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import List, Tuple
+
+from ..registry import MigrationRegistry
+from .base import BaseMigration, MigrationResult
+
+MIGRATION_ID = "0.12.1_remove_kitty_specs_from_gitignore"
+MIGRATION_VERSION = "0.12.1"
+MIGRATION_DESCRIPTION = "Remove kitty-specs/ from main repo .gitignore to allow tracking feature specs"
+
+# Patterns to REMOVE (block entire kitty-specs directory)
+PATTERNS_TO_REMOVE = [
+    r"^kitty-specs/?$",          # kitty-specs or kitty-specs/
+    r"^/kitty-specs/?$",         # /kitty-specs or /kitty-specs/
+]
+
+# Patterns to KEEP (worktree-specific, prevent merge conflicts)
+PATTERNS_TO_KEEP = [
+    r"kitty-specs/\*\*/tasks/",  # kitty-specs/**/tasks/*.md
+    r"kitty-specs/.*/tasks/",    # kitty-specs/*/tasks/*.md
+]
+
+
+def is_blocking_pattern(line: str) -> bool:
+    """Check if a line blocks the entire kitty-specs directory.
+
+    Returns True for patterns like:
+    - kitty-specs
+    - kitty-specs/
+    - /kitty-specs
+    - /kitty-specs/
+
+    Returns False for specific subpath patterns like:
+    - kitty-specs/**/tasks/*.md (this is fine, used in worktrees)
+    """
+    stripped = line.strip()
+
+    # Skip comments and empty lines
+    if not stripped or stripped.startswith("#"):
+        return False
+
+    # Check if it's a specific subpath pattern (KEEP these)
+    for keep_pattern in PATTERNS_TO_KEEP:
+        if re.search(keep_pattern, stripped):
+            return False
+
+    # Check if it blocks the entire directory (REMOVE these)
+    for remove_pattern in PATTERNS_TO_REMOVE:
+        if re.match(remove_pattern, stripped):
+            return True
+
+    return False
+
+
+def find_blocking_entries(gitignore_path: Path) -> List[Tuple[int, str]]:
+    """Find all lines that block kitty-specs/ entirely.
+
+    Returns list of (line_number, line_content) tuples.
+    Line numbers are 1-indexed for user display.
+    """
+    if not gitignore_path.exists():
+        return []
+
+    blocking_entries = []
+    content = gitignore_path.read_text(encoding="utf-8-sig", errors="ignore")
+
+    for i, line in enumerate(content.splitlines(), start=1):
+        if is_blocking_pattern(line):
+            blocking_entries.append((i, line.strip()))
+
+    return blocking_entries
+
+
+def remove_blocking_entries(gitignore_path: Path, dry_run: bool = False) -> Tuple[List[str], List[str]]:
+    """Remove entries that block kitty-specs/ from .gitignore.
+
+    Returns (changes, errors) tuple.
+    """
+    changes: List[str] = []
+    errors: List[str] = []
+
+    if not gitignore_path.exists():
+        changes.append("No .gitignore file found")
+        return changes, errors
+
+    try:
+        content = gitignore_path.read_text(encoding="utf-8-sig", errors="ignore")
+    except OSError as e:
+        errors.append(f"Failed to read .gitignore: {e}")
+        return changes, errors
+
+    lines = content.splitlines(keepends=True)
+    new_lines = []
+    removed_count = 0
+
+    for i, line in enumerate(lines, start=1):
+        if is_blocking_pattern(line):
+            changes.append(f"Line {i}: Removed '{line.strip()}'")
+            removed_count += 1
+            # Skip this line (don't add to new_lines)
+        else:
+            new_lines.append(line)
+
+    if removed_count == 0:
+        changes.append("No blocking kitty-specs/ entries found in .gitignore")
+        return changes, errors
+
+    if dry_run:
+        changes.insert(0, f"Would remove {removed_count} blocking entries from .gitignore")
+        return changes, errors
+
+    # Write updated content
+    try:
+        new_content = "".join(new_lines)
+        # Clean up any resulting double blank lines
+        new_content = re.sub(r"\n{3,}", "\n\n", new_content)
+        gitignore_path.write_text(new_content, encoding="utf-8")
+        changes.insert(0, f"Removed {removed_count} blocking entries from .gitignore")
+    except OSError as e:
+        errors.append(f"Failed to write .gitignore: {e}")
+
+    return changes, errors
+
+
+@MigrationRegistry.register
+class RemoveKittySpecsFromGitignoreMigration(BaseMigration):
+    """Remove kitty-specs/ from main repo .gitignore.
+
+    Feature specifications must be tracked in git. If kitty-specs/ is in
+    .gitignore, git add operations fail during feature creation.
+    """
+
+    migration_id = MIGRATION_ID
+    description = MIGRATION_DESCRIPTION
+    target_version = MIGRATION_VERSION
+
+    def detect(self, project_path: Path) -> bool:
+        """Check if .gitignore contains blocking kitty-specs/ entries."""
+        gitignore_path = project_path / ".gitignore"
+        blocking_entries = find_blocking_entries(gitignore_path)
+        return len(blocking_entries) > 0
+
+    def can_apply(self, project_path: Path) -> tuple[bool, str]:
+        """Check if we can modify .gitignore."""
+        gitignore_path = project_path / ".gitignore"
+
+        if not gitignore_path.exists():
+            return True, ""
+
+        try:
+            gitignore_path.read_text(encoding="utf-8-sig", errors="ignore")
+            return True, ""
+        except OSError as e:
+            return False, f".gitignore is not readable: {e}"
+
+    def apply(self, project_path: Path, dry_run: bool = False) -> MigrationResult:
+        """Remove blocking kitty-specs/ entries from .gitignore."""
+        gitignore_path = project_path / ".gitignore"
+        changes, errors = remove_blocking_entries(gitignore_path, dry_run=dry_run)
+
+        return MigrationResult(
+            success=len(errors) == 0,
+            changes_made=changes,
+            errors=errors,
+            warnings=[],
+        )

specify_cli/upgrade/migrations/m_0_2_0_specify_to_kittify.py

@@ -0,0 +1,80 @@
+"""Migration: Rename .specify/ to .kittify/ and /specs/ to /kitty-specs/."""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+from ..registry import MigrationRegistry
+from .base import BaseMigration, MigrationResult
+
+
+@MigrationRegistry.register
+class SpecifyToKittifyMigration(BaseMigration):
+    """Migrate from .specify/ to .kittify/ and /specs/ to /kitty-specs/.
+
+    This migration handles the rebranding from the original "specify"
+    naming to "kittify" naming introduced in v0.2.0.
+    """
+
+    migration_id = "0.2.0_specify_to_kittify"
+    description = "Rename .specify/ to .kittify/ and /specs/ to /kitty-specs/"
+    target_version = "0.2.0"
+
+    def detect(self, project_path: Path) -> bool:
+        """Check if project uses old .specify/ directory."""
+        return (project_path / ".specify").exists()
+
+    def can_apply(self, project_path: Path) -> tuple[bool, str]:
+        """Check if migration can be safely applied."""
+        specify_dir = project_path / ".specify"
+        kittify_dir = project_path / ".kittify"
+
+        if not specify_dir.exists():
+            return False, ".specify/ directory does not exist"
+
+        if kittify_dir.exists():
+            return False, ".kittify/ already exists - manual merge required"
+
+        specs_dir = project_path / "specs"
+        kitty_specs_dir = project_path / "kitty-specs"
+
+        if specs_dir.exists() and kitty_specs_dir.exists():
+            return False, "Both /specs/ and /kitty-specs/ exist - manual merge required"
+
+        return True, ""
+
+    def apply(self, project_path: Path, dry_run: bool = False) -> MigrationResult:
+        """Apply the migration."""
+        changes: list[str] = []
+        errors: list[str] = []
+
+        specify_dir = project_path / ".specify"
+        kittify_dir = project_path / ".kittify"
+        specs_dir = project_path / "specs"
+        kitty_specs_dir = project_path / "kitty-specs"
+
+        # Rename .specify/ to .kittify/
+        if specify_dir.exists():
+            if dry_run:
+                changes.append(f"Would rename {specify_dir} to {kittify_dir}")
+            else:
+                try:
+                    shutil.move(str(specify_dir), str(kittify_dir))
+                    changes.append(f"Renamed {specify_dir} to {kittify_dir}")
+                except OSError as e:
+                    errors.append(f"Failed to rename .specify/ to .kittify/: {e}")
+
+        # Rename /specs/ to /kitty-specs/
+        if specs_dir.exists() and not kitty_specs_dir.exists():
+            if dry_run:
+                changes.append(f"Would rename {specs_dir} to {kitty_specs_dir}")
+            else:
+                try:
+                    shutil.move(str(specs_dir), str(kitty_specs_dir))
+                    changes.append(f"Renamed {specs_dir} to {kitty_specs_dir}")
+                except OSError as e:
+                    errors.append(f"Failed to rename /specs/ to /kitty-specs/: {e}")
+
+        success = len(errors) == 0
+        return MigrationResult(success=success, changes_made=changes, errors=errors)

specify_cli/upgrade/migrations/m_0_4_8_gitignore_agents.py

@@ -0,0 +1,118 @@
+"""Migration: Ensure all 12 agent directories are in .gitignore."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..registry import MigrationRegistry
+from .base import BaseMigration, MigrationResult
+
+
+@MigrationRegistry.register
+class GitignoreAgentsMigration(BaseMigration):
+    """Ensure all 12 agent directories are in .gitignore.
+
+    This migration adds protection for all known AI agent directories
+    that should never be committed to git (they contain auth tokens).
+    """
+
+    migration_id = "0.4.8_gitignore_agents"
+    description = "Add all 12 AI agent directories to .gitignore"
+    target_version = "0.4.8"
+
+    EXPECTED_AGENTS = [
+        ".claude/",
+        ".codex/",
+        ".opencode/",
+        ".windsurf/",
+        ".gemini/",
+        ".cursor/",
+        ".qwen/",
+        ".kilocode/",
+        ".augment/",
+        ".roo/",
+        ".amazonq/",
+        ".github/copilot/",
+    ]
+
+    def detect(self, project_path: Path) -> bool:
+        """Check if .gitignore is missing agent directories."""
+        gitignore = project_path / ".gitignore"
+        if not gitignore.exists():
+            return True
+
+        try:
+            content = gitignore.read_text(encoding="utf-8-sig", errors="ignore")
+        except OSError:
+            return True
+
+        missing = [d for d in self.EXPECTED_AGENTS if d not in content]
+        return len(missing) > 0
+
+    def can_apply(self, project_path: Path) -> tuple[bool, str]:
+        """Check if we can modify .gitignore."""
+        gitignore = project_path / ".gitignore"
+
+        if gitignore.exists():
+            try:
+                # Test read access; tolerate BOM and ignore invalid UTF-8 bytes
+                gitignore.read_text(encoding="utf-8-sig", errors="ignore")
+            except (OSError, UnicodeDecodeError):
+                return False, ".gitignore is not readable"
+
+        return True, ""
+
+    def apply(self, project_path: Path, dry_run: bool = False) -> MigrationResult:
+        """Apply gitignore updates."""
+        changes: list[str] = []
+        warnings: list[str] = []
+        errors: list[str] = []
+
+        gitignore = project_path / ".gitignore"
+
+        # Determine what needs to be added
+        existing_content = ""
+        if gitignore.exists():
+            try:
+                existing_content = gitignore.read_text(encoding="utf-8-sig", errors="ignore")
+            except OSError as e:
+                errors.append(f"Failed to read .gitignore: {e}")
+                return MigrationResult(success=False, errors=errors)
+
+        missing = [d for d in self.EXPECTED_AGENTS if d not in existing_content]
+
+        if not missing:
+            changes.append("All agent directories already in .gitignore")
+            return MigrationResult(success=True, changes_made=changes)
+
+        if dry_run:
+            changes.append(f"Would add {len(missing)} agent directories to .gitignore")
+            for d in missing:
+                changes.append(f"  - {d}")
+            return MigrationResult(success=True, changes_made=changes)
+
+        # Build new content
+        new_entries = "\n# AI Agent directories (added by Spec Kitty CLI)\n"
+        new_entries += "# These contain auth tokens and should NEVER be committed\n"
+        for d in missing:
+            new_entries += f"{d}\n"
+
+        # Ensure existing content ends with newline
+        if existing_content and not existing_content.endswith("\n"):
+            existing_content += "\n"
+
+        new_content = existing_content + new_entries
+
+        try:
+            gitignore.write_text(new_content, encoding="utf-8")
+            changes.append(f"Added {len(missing)} agent directories to .gitignore")
+        except OSError as e:
+            errors.append(f"Failed to write .gitignore: {e}")
+
+        success = len(errors) == 0
+        return MigrationResult(
+            success=success,
+            changes_made=changes,
+            errors=errors,
+            warnings=warnings,
+        )