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

specify_cli/templates/vscode-settings.json

@@ -0,0 +1,13 @@
+{
+    "chat.promptFilesRecommendations": {
+        "spec-kitty.constitution": true,
+        "spec-kitty.specify": true,
+        "spec-kitty.plan": true,
+        "spec-kitty.tasks": true,
+        "spec-kitty.implement": true
+    },
+    "chat.tools.terminal.autoApprove": {
+        ".kittify/scripts/bash/": true,
+        ".kittify/scripts/ps/": true
+    }
+}

specify_cli/text_sanitization.py

@@ -0,0 +1,225 @@
+"""Text sanitization utilities for preventing encoding errors.
+
+This module provides utilities to normalize Windows-1252 smart quotes and other
+problematic characters that can cause UTF-8 encoding errors in markdown files.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Optional
+
+__all__ = [
+    "sanitize_markdown_text",
+    "sanitize_file",
+    "detect_problematic_characters",
+    "PROBLEMATIC_CHARS",
+]
+
+# Map of Windows-1252 / problematic characters to safe UTF-8 replacements
+PROBLEMATIC_CHARS = {
+    # Smart quotes (Windows-1252 bytes 0x91-0x94)
+    "\u2018": "'",  # LEFT SINGLE QUOTATION MARK → apostrophe
+    "\u2019": "'",  # RIGHT SINGLE QUOTATION MARK → apostrophe
+    "\u201c": '"',  # LEFT DOUBLE QUOTATION MARK → straight quote
+    "\u201d": '"',  # RIGHT DOUBLE QUOTATION MARK → straight quote
+    # Em/en dashes
+    "\u2013": "--",  # EN DASH → double hyphen
+    "\u2014": "---",  # EM DASH → triple hyphen
+    # Mathematical operators that may come from cp1252
+    "\u00b1": "+/-",  # PLUS-MINUS SIGN → +/-
+    "\u00d7": "x",  # MULTIPLICATION SIGN → x
+    "\u00f7": "/",  # DIVISION SIGN → /
+    # Ellipsis
+    "\u2026": "...",  # HORIZONTAL ELLIPSIS → three periods
+    # Bullets
+    "\u2022": "*",  # BULLET → asterisk
+    "\u2023": ">",  # TRIANGULAR BULLET → greater than
+    # Degree symbol (often problematic)
+    "\u00b0": " degrees",  # DEGREE SIGN → " degrees"
+    # Non-breaking space (invisible but causes issues)
+    "\u00a0": " ",  # NO-BREAK SPACE → regular space
+    # Trademark/copyright symbols
+    "\u2122": "(TM)",  # TRADE MARK SIGN
+    "\u00a9": "(C)",  # COPYRIGHT SIGN
+    "\u00ae": "(R)",  # REGISTERED SIGN
+}
+
+# Compile regex for detecting any problematic character
+_PROBLEMATIC_PATTERN = re.compile(
+    "[" + "".join(re.escape(char) for char in PROBLEMATIC_CHARS.keys()) + "]"
+)
+
+
+def sanitize_markdown_text(text: str, *, preserve_utf8: bool = False) -> str:
+    """Sanitize markdown text by replacing problematic characters.
+
+    Args:
+        text: The markdown text to sanitize
+        preserve_utf8: If True, only replace characters that cause encoding issues.
+                      If False (default), replace all problematic characters for
+                      maximum compatibility.
+
+    Returns:
+        Sanitized text with problematic characters replaced
+
+    Examples:
+        >>> sanitize_markdown_text("User's "favorite" feature")
+        'User\\'s "favorite" feature'
+
+        >>> sanitize_markdown_text("Price: $100 ± $10")
+        'Price: $100 +/- $10'
+
+        >>> sanitize_markdown_text("Temperature: 72° outside")
+        'Temperature: 72 degrees outside'
+    """
+    if not text:
+        return text
+
+    # Replace each problematic character with its safe equivalent
+    result = text
+    for problematic, replacement in PROBLEMATIC_CHARS.items():
+        if problematic in result:
+            result = result.replace(problematic, replacement)
+
+    return result
+
+
+def detect_problematic_characters(
+    text: str,
+) -> list[tuple[int, int, str, str]]:
+    """Detect problematic characters in text and return their locations.
+
+    Args:
+        text: The text to check
+
+    Returns:
+        List of tuples: (line_number, column, character, suggested_replacement)
+        Line numbers are 1-indexed, columns are 0-indexed.
+
+    Examples:
+        >>> text = "Line 1\\nUser's "test"\\nLine 3"
+        >>> issues = detect_problematic_characters(text)
+        >>> len(issues)
+        3
+        >>> issues[0]
+        (2, 4, '\u2019', "'")
+    """
+    issues: list[tuple[int, int, str, str]] = []
+
+    lines = text.splitlines(keepends=True)
+    for line_num, line in enumerate(lines, start=1):
+        for match in _PROBLEMATIC_PATTERN.finditer(line):
+            char = match.group(0)
+            replacement = PROBLEMATIC_CHARS.get(char, "?")
+            issues.append((line_num, match.start(), char, replacement))
+
+    return issues
+
+
+def sanitize_file(
+    file_path: Path,
+    *,
+    backup: bool = True,
+    dry_run: bool = False,
+) -> tuple[bool, Optional[str]]:
+    """Sanitize a markdown file in place.
+
+    Args:
+        file_path: Path to the markdown file to sanitize
+        backup: If True, create a .bak file before modifying
+        dry_run: If True, only check and report, don't modify
+
+    Returns:
+        Tuple of (was_modified, error_message)
+        - was_modified: True if the file had problematic characters
+        - error_message: None if successful, error message if failed
+
+    Examples:
+        >>> from pathlib import Path
+        >>> from tempfile import NamedTemporaryFile
+        >>> with NamedTemporaryFile(mode='w', suffix='.md', delete=False) as f:
+        ...     f.write('User's "test"')
+        ...     tmp_path = Path(f.name)
+        >>> modified, error = sanitize_file(tmp_path, backup=False)
+        >>> modified
+        True
+        >>> tmp_path.read_text()
+        'User\\'s "test"'
+        >>> tmp_path.unlink()  # cleanup
+    """
+    if not file_path.exists():
+        return False, f"File not found: {file_path}"
+
+    try:
+        # Try reading as UTF-8 first
+        try:
+            original_text = file_path.read_text(encoding="utf-8-sig")
+            encoding_issue = False
+        except UnicodeDecodeError:
+            # Fall back to cp1252 or latin-1
+            encoding_issue = True
+            original_bytes = file_path.read_bytes()
+            for encoding in ("cp1252", "latin-1"):
+                try:
+                    original_text = original_bytes.decode(encoding)
+                    break
+                except UnicodeDecodeError:
+                    continue
+            else:
+                # Last resort: replace invalid characters
+                original_text = original_bytes.decode("utf-8", errors="replace")
+
+        # Strip UTF-8 BOM if present in the text
+        original_text = original_text.lstrip('\ufeff')
+
+        # Sanitize the text
+        sanitized_text = sanitize_markdown_text(original_text)
+
+        # Check if any changes were made
+        if sanitized_text == original_text and not encoding_issue:
+            return False, None  # No changes needed
+
+        if dry_run:
+            return True, None  # Would modify but dry run
+
+        # Create backup if requested
+        if backup:
+            backup_path = file_path.with_suffix(file_path.suffix + ".bak")
+            backup_path.write_bytes(file_path.read_bytes())
+
+        # Write sanitized content
+        file_path.write_text(sanitized_text, encoding="utf-8")
+        return True, None
+
+    except Exception as exc:
+        return False, f"Error sanitizing {file_path}: {exc}"
+
+
+def sanitize_directory(
+    directory: Path,
+    *,
+    pattern: str = "**/*.md",
+    backup: bool = False,
+    dry_run: bool = False,
+) -> dict[str, tuple[bool, Optional[str]]]:
+    """Sanitize all markdown files in a directory.
+
+    Args:
+        directory: Directory to scan
+        pattern: Glob pattern for files to sanitize (default: **/*.md)
+        backup: If True, create .bak files before modifying
+        dry_run: If True, only check and report, don't modify
+
+    Returns:
+        Dictionary mapping file paths to (was_modified, error_message) tuples
+    """
+    results: dict[str, tuple[bool, Optional[str]]] = {}
+
+    for file_path in directory.glob(pattern):
+        if file_path.is_file():
+            result = sanitize_file(file_path, backup=backup, dry_run=dry_run)
+            results[str(file_path)] = result
+
+    return results

specify_cli/upgrade/__init__.py

@@ -0,0 +1,18 @@
+"""Spec Kitty upgrade system for migrating projects between versions."""
+
+from __future__ import annotations
+
+from .metadata import MigrationRecord, ProjectMetadata
+from .detector import VersionDetector
+from .registry import MigrationRegistry, register
+from .runner import MigrationRunner, UpgradeResult
+
+__all__ = [
+    "MigrationRecord",
+    "ProjectMetadata",
+    "VersionDetector",
+    "MigrationRegistry",
+    "MigrationRunner",
+    "UpgradeResult",
+    "register",
+]

specify_cli/upgrade/detector.py

@@ -0,0 +1,239 @@
+"""Version detection for Spec Kitty projects."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import List
+
+from .metadata import ProjectMetadata
+
+
+class VersionDetector:
+    """Detects project version through heuristics when metadata is missing."""
+
+    # Agent directories that should be in .gitignore (v0.4.8+)
+    EXPECTED_AGENTS = [
+        ".claude/",
+        ".codex/",
+        ".opencode/",
+        ".windsurf/",
+        ".gemini/",
+        ".cursor/",
+        ".qwen/",
+        ".kilocode/",
+        ".augment/",
+        ".roo/",
+        ".amazonq/",
+        ".github/copilot/",
+    ]
+
+    def __init__(self, project_path: Path):
+        """Initialize the detector.
+
+        Args:
+            project_path: Root of the project
+        """
+        self.project_path = project_path
+        self.kittify_dir = project_path / ".kittify"
+        self.specify_dir = project_path / ".specify"  # Old name
+
+    def detect_version(self) -> str:
+        """Detect the approximate version of a project.
+
+        Returns:
+            A version string like "0.1.0" (oldest detectable)
+            or "0.6.7" (current).
+        """
+        # First try to load from metadata
+        if self.kittify_dir.exists():
+            metadata = ProjectMetadata.load(self.kittify_dir)
+            if metadata:
+                return metadata.version
+
+        # Heuristic detection based on directory structure
+        return self._detect_from_structure()
+
+    def _detect_from_structure(self) -> str:
+        """Detect version from project structure."""
+        # v0.1.x: Uses .specify/ directory and /specs/
+        if self.specify_dir.exists():
+            return "0.1.0"
+
+        # No .kittify at all - not initialized or very old
+        if not self.kittify_dir.exists():
+            return "0.0.0"
+
+        # Check for command-templates vs commands directory
+        # v0.6.5+ uses command-templates/
+        templates_dir = self.kittify_dir / "templates"
+        missions_dir = self.kittify_dir / "missions"
+
+        # Check templates location
+        has_command_templates = (templates_dir / "command-templates").exists()
+        has_old_commands = (templates_dir / "commands").exists()
+
+        # Check missions for command-templates
+        has_mission_command_templates = False
+        has_mission_commands = False
+        if missions_dir.exists():
+            for mission in missions_dir.iterdir():
+                if mission.is_dir():
+                    if (mission / "command-templates").exists():
+                        has_mission_command_templates = True
+                    if (mission / "commands").exists():
+                        has_mission_commands = True
+
+        # v0.6.5+: Has command-templates (not commands)
+        if has_command_templates or has_mission_command_templates:
+            if not has_old_commands and not has_mission_commands:
+                return "0.6.5"
+
+        # v0.6.4 and earlier: Has old commands/ directory
+        if has_old_commands or has_mission_commands:
+            return "0.6.4"
+
+        # Check for git hooks (v0.5.0+)
+        git_hooks = self.project_path / ".git" / "hooks"
+        if git_hooks.exists() and (git_hooks / "pre-commit").exists():
+            try:
+                hook_content = (git_hooks / "pre-commit").read_text(
+                    encoding="utf-8", errors="ignore"
+                )
+                if "spec-kitty" in hook_content.lower() or "encoding" in hook_content.lower():
+                    return "0.5.0"
+            except OSError:
+                pass
+
+        # Check .gitignore for agent directories (v0.4.8+)
+        gitignore = self.project_path / ".gitignore"
+        if gitignore.exists():
+            try:
+                content = gitignore.read_text(encoding="utf-8-sig", errors="ignore")
+                agent_dirs = [".claude/", ".codex/", ".gemini/", ".cursor/"]
+                agent_count = sum(1 for d in agent_dirs if d in content)
+                if agent_count >= 4:
+                    return "0.4.8"
+            except OSError:
+                pass
+
+        # Check for missions directory (v0.2.0+)
+        if missions_dir.exists():
+            return "0.2.0"
+
+        # Default to oldest .kittify-based version
+        return "0.2.0"
+
+    def get_needed_migrations(self, target_version: str) -> List[str]:
+        """Get list of migration IDs needed to reach target version.
+
+        Args:
+            target_version: Version to upgrade to
+
+        Returns:
+            List of migration IDs in order
+        """
+        from .registry import MigrationRegistry
+
+        current = self.detect_version()
+        migrations = MigrationRegistry.get_applicable(current, target_version)
+        return [m.migration_id for m in migrations]
+
+    def has_old_commands_structure(self) -> bool:
+        """Check if the project uses old commands/ directories.
+
+        Returns:
+            True if old commands/ directories exist
+        """
+        templates_commands = self.kittify_dir / "templates" / "commands"
+        if templates_commands.exists():
+            return True
+
+        missions_dir = self.kittify_dir / "missions"
+        if missions_dir.exists():
+            for mission in missions_dir.iterdir():
+                if mission.is_dir() and (mission / "commands").exists():
+                    return True
+
+        return False
+
+    def has_old_specify_structure(self) -> bool:
+        """Check if the project uses old .specify/ structure.
+
+        Returns:
+            True if .specify/ directory exists
+        """
+        return self.specify_dir.exists()
+
+    def count_missing_agent_gitignore_entries(self) -> int:
+        """Count how many agent directories are missing from .gitignore.
+
+        Returns:
+            Number of missing entries
+        """
+        gitignore = self.project_path / ".gitignore"
+        if not gitignore.exists():
+            return len(self.EXPECTED_AGENTS)
+
+        try:
+            content = gitignore.read_text(encoding="utf-8-sig", errors="ignore")
+        except OSError:
+            return len(self.EXPECTED_AGENTS)
+
+        missing = [d for d in self.EXPECTED_AGENTS if d not in content]
+        return len(missing)
+
+    @classmethod
+    def detect_broken_mission_system(cls, project_path: Path) -> bool:
+        """Detect if the mission system has corrupted files.
+
+        Checks for:
+        1. Missing mission.yaml files in mission directories
+        2. Invalid YAML syntax in mission.yaml files
+        3. Missing required fields (name)
+
+        Args:
+            project_path: Path to the project root
+
+        Returns:
+            True if mission system is broken/corrupted, False if healthy
+        """
+        import yaml
+
+        missions_dir = project_path / ".kittify" / "missions"
+
+        # No missions directory at all is broken
+        if not missions_dir.exists():
+            return True
+
+        # Check each mission directory
+        has_any_mission = False
+        for mission_dir in missions_dir.iterdir():
+            if not mission_dir.is_dir():
+                continue
+
+            has_any_mission = True
+            mission_yaml = mission_dir / "mission.yaml"
+
+            # Check if mission.yaml exists
+            if not mission_yaml.exists():
+                return True
+
+            # Check if mission.yaml is valid YAML with required fields
+            try:
+                with open(mission_yaml, encoding="utf-8") as f:
+                    data = yaml.safe_load(f)
+
+                # Check required fields
+                if not data or "name" not in data:
+                    return True
+
+            except yaml.YAMLError:
+                return True
+            except OSError:
+                return True
+
+        # If no mission directories found, that's broken
+        if not has_any_mission:
+            return True
+
+        return False

specify_cli/upgrade/metadata.py

@@ -0,0 +1,182 @@
+"""Project metadata management for Spec Kitty upgrade system."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+from typing import List, Optional
+
+import yaml
+
+
+@dataclass
+class MigrationRecord:
+    """Record of a single migration application."""
+
+    id: str
+    applied_at: datetime
+    result: str  # "success", "skipped", "failed"
+    notes: Optional[str] = None
+
+
+@dataclass
+class ProjectMetadata:
+    """Metadata for a Spec Kitty project stored in .kittify/metadata.yaml."""
+
+    version: str
+    initialized_at: datetime
+    last_upgraded_at: Optional[datetime] = None
+    python_version: str = ""
+    platform: str = ""
+    platform_version: str = ""
+    applied_migrations: List[MigrationRecord] = field(default_factory=list)
+
+    @classmethod
+    def load(cls, kittify_dir: Path) -> Optional["ProjectMetadata"]:
+        """Load metadata from .kittify/metadata.yaml.
+
+        Args:
+            kittify_dir: Path to the .kittify directory
+
+        Returns:
+            ProjectMetadata if file exists, None otherwise
+        """
+        metadata_path = kittify_dir / "metadata.yaml"
+        if not metadata_path.exists():
+            return None
+
+        try:
+            with open(metadata_path, "r", encoding="utf-8-sig") as f:
+                data = yaml.safe_load(f)
+        except (OSError, yaml.YAMLError):
+            return None
+
+        if not data:
+            return None
+
+        spec_kitty = data.get("spec_kitty", {})
+        env = data.get("environment", {})
+        migrations_data = data.get("migrations", {}).get("applied", [])
+
+        applied = []
+        for m in migrations_data:
+            try:
+                applied.append(
+                    MigrationRecord(
+                        id=m["id"],
+                        applied_at=datetime.fromisoformat(m["applied_at"]),
+                        result=m["result"],
+                        notes=m.get("notes"),
+                    )
+                )
+            except (KeyError, ValueError):
+                # Skip malformed migration records
+                continue
+
+        initialized_at_str = spec_kitty.get("initialized_at")
+        try:
+            initialized_at = (
+                datetime.fromisoformat(initialized_at_str)
+                if initialized_at_str
+                else datetime.now()
+            )
+        except ValueError:
+            initialized_at = datetime.now()
+
+        last_upgraded_str = spec_kitty.get("last_upgraded_at")
+        try:
+            last_upgraded_at = (
+                datetime.fromisoformat(last_upgraded_str) if last_upgraded_str else None
+            )
+        except ValueError:
+            last_upgraded_at = None
+
+        return cls(
+            version=spec_kitty.get("version", "unknown"),
+            initialized_at=initialized_at,
+            last_upgraded_at=last_upgraded_at,
+            python_version=env.get("python_version", ""),
+            platform=env.get("platform", ""),
+            platform_version=env.get("platform_version", ""),
+            applied_migrations=applied,
+        )
+
+    def save(self, kittify_dir: Path) -> None:
+        """Save metadata to .kittify/metadata.yaml.
+
+        Args:
+            kittify_dir: Path to the .kittify directory
+        """
+        metadata_path = kittify_dir / "metadata.yaml"
+        kittify_dir.mkdir(parents=True, exist_ok=True)
+
+        data = {
+            "spec_kitty": {
+                "version": self.version,
+                "initialized_at": self.initialized_at.isoformat(),
+                "last_upgraded_at": (
+                    self.last_upgraded_at.isoformat() if self.last_upgraded_at else None
+                ),
+            },
+            "environment": {
+                "python_version": self.python_version,
+                "platform": self.platform,
+                "platform_version": self.platform_version,
+            },
+            "migrations": {
+                "applied": [
+                    {
+                        "id": m.id,
+                        "applied_at": m.applied_at.isoformat(),
+                        "result": m.result,
+                        "notes": m.notes,
+                    }
+                    for m in self.applied_migrations
+                ]
+            },
+        }
+
+        # Add header comment
+        header = (
+            "# Spec Kitty Project Metadata\n"
+            "# Auto-generated by spec-kitty init/upgrade\n"
+            "# DO NOT EDIT MANUALLY\n\n"
+        )
+
+        with open(metadata_path, "w", encoding="utf-8") as f:
+            f.write(header)
+            yaml.dump(data, f, default_flow_style=False, sort_keys=False)
+
+    def has_migration(self, migration_id: str) -> bool:
+        """Check if a migration has been successfully applied.
+
+        Args:
+            migration_id: The ID of the migration to check
+
+        Returns:
+            True if migration was applied successfully
+        """
+        return any(
+            m.id == migration_id and m.result == "success"
+            for m in self.applied_migrations
+        )
+
+    def record_migration(
+        self, migration_id: str, result: str, notes: Optional[str] = None
+    ) -> None:
+        """Record a migration application.
+
+        Args:
+            migration_id: The ID of the migration
+            result: The result ("success", "skipped", "failed")
+            notes: Optional notes about the migration
+        """
+        self.applied_migrations.append(
+            MigrationRecord(
+                id=migration_id,
+                applied_at=datetime.now(),
+                result=result,
+                notes=notes,
+            )
+        )