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

specify_cli/cli/commands/upgrade.py

@@ -0,0 +1,249 @@
+"""Upgrade command implementation for Spec Kitty CLI."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Optional
+
+import typer
+from rich.panel import Panel
+from rich.table import Table
+
+from specify_cli.cli.helpers import console, show_banner
+
+
+def upgrade(
+    dry_run: bool = typer.Option(
+        False, "--dry-run", help="Preview changes without applying"
+    ),
+    force: bool = typer.Option(False, "--force", help="Skip confirmation prompts"),
+    target: Optional[str] = typer.Option(
+        None, "--target", help="Target version (defaults to current CLI version)"
+    ),
+    json_output: bool = typer.Option(False, "--json", help="Output results as JSON"),
+    verbose: bool = typer.Option(
+        False, "--verbose", "-v", help="Show detailed migration information"
+    ),
+    no_worktrees: bool = typer.Option(
+        False, "--no-worktrees", help="Skip upgrading worktrees"
+    ),
+) -> None:
+    """Upgrade a Spec Kitty project to the current version.
+
+    Detects the project's current version and applies all necessary migrations
+    to bring it up to date with the installed CLI version.
+
+    Examples:
+        spec-kitty upgrade              # Upgrade to current version
+        spec-kitty upgrade --dry-run    # Preview changes
+        spec-kitty upgrade --target 0.6.5  # Upgrade to specific version
+    """
+    if not json_output:
+        show_banner()
+
+    project_path = Path.cwd()
+    kittify_dir = project_path / ".kittify"
+    specify_dir = project_path / ".specify"  # Old name
+
+    # Check if this is a Spec Kitty project
+    if not kittify_dir.exists() and not specify_dir.exists():
+        if json_output:
+            console.print(json.dumps({"error": "Not a Spec Kitty project"}))
+        else:
+            console.print("[red]Error:[/red] Not a Spec Kitty project.")
+            console.print(
+                "[dim]Run 'spec-kitty init' to initialize a project.[/dim]"
+            )
+        raise typer.Exit(1)
+
+    # Import upgrade system (lazy to avoid circular imports)
+    from specify_cli.upgrade.detector import VersionDetector
+    from specify_cli.upgrade.registry import MigrationRegistry
+    from specify_cli.upgrade.runner import MigrationRunner
+
+    # Import migrations to register them
+    from specify_cli.upgrade import migrations  # noqa: F401
+
+    # Detect current version
+    detector = VersionDetector(project_path)
+    current_version = detector.detect_version()
+
+    # Determine target version
+    if target is None:
+        from specify_cli import __version__
+
+        target_version = __version__
+    else:
+        target_version = target
+
+    if not json_output:
+        console.print(f"[cyan]Current version:[/cyan] {current_version}")
+        console.print(f"[cyan]Target version:[/cyan]  {target_version}")
+        console.print()
+
+    # Get needed migrations
+    # Handle "unknown" version by treating it as very old (0.0.0)
+    version_for_migration = "0.0.0" if current_version == "unknown" else current_version
+    migrations_needed = MigrationRegistry.get_applicable(version_for_migration, target_version, project_path=project_path)
+
+    if not migrations_needed:
+        if json_output:
+            console.print(
+                json.dumps(
+                    {
+                        "status": "up_to_date",
+                        "current_version": current_version,
+                        "target_version": target_version,
+                    }
+                )
+            )
+        else:
+            console.print("[green]Project is already up to date![/green]")
+        return
+
+    # Show migration plan
+    if not json_output:
+        table = Table(
+            title="Migration Plan", show_lines=False, header_style="bold cyan"
+        )
+        table.add_column("Migration", style="bright_white")
+        table.add_column("Description", style="dim")
+        table.add_column("Target", style="cyan")
+
+        for migration in migrations_needed:
+            table.add_row(
+                migration.migration_id,
+                migration.description,
+                migration.target_version,
+            )
+
+        console.print(table)
+        console.print()
+
+        if verbose:
+            # Show detection results
+            console.print("[dim]Detection results:[/dim]")
+            for migration in migrations_needed:
+                detected = migration.detect(project_path)
+                can_apply, reason = migration.can_apply(project_path)
+                status = "[green]ready[/green]" if detected and can_apply else "[yellow]skipped[/yellow]"
+                console.print(f"  {migration.migration_id}: {status}")
+                if not can_apply and reason:
+                    console.print(f"    [dim]{reason}[/dim]")
+            console.print()
+
+    # Confirm if not dry-run and not forced
+    if not dry_run and not force:
+        proceed = typer.confirm(
+            f"Apply {len(migrations_needed)} migration(s)?",
+            default=True,
+        )
+        if not proceed:
+            console.print("[yellow]Upgrade cancelled.[/yellow]")
+            raise typer.Exit(0)
+
+    # Run migrations
+    runner = MigrationRunner(project_path, console)
+    result = runner.upgrade(
+        target_version,
+        dry_run=dry_run,
+        force=force,
+        include_worktrees=not no_worktrees,
+    )
+
+    if json_output:
+        # Build detailed migrations array
+        migrations_detail = []
+        for migration in migrations_needed:
+            status = "applied" if migration.migration_id in result.migrations_applied else (
+                "skipped" if migration.migration_id in result.migrations_skipped else "pending"
+            )
+            migrations_detail.append({
+                "id": migration.migration_id,
+                "description": migration.description,
+                "target_version": migration.target_version,
+                "status": status,
+            })
+
+        output = {
+            "status": "success" if result.success else "failed",
+            "current_version": result.from_version,
+            "target_version": result.to_version,
+            "dry_run": result.dry_run,
+            "migrations": migrations_detail,
+            "migrations_applied": result.migrations_applied,
+            "migrations_skipped": result.migrations_skipped,
+            "success": result.success,
+            "errors": result.errors,
+            "warnings": result.warnings,
+        }
+        console.print(json.dumps(output, indent=2))
+        return
+
+    # Display results
+    console.print()
+
+    if result.dry_run:
+        console.print(
+            Panel(
+                "[yellow]DRY RUN[/yellow] - No changes were made",
+                border_style="yellow",
+            )
+        )
+
+    if result.migrations_applied:
+        console.print("[green]Migrations applied:[/green]")
+        for m in result.migrations_applied:
+            console.print(f"  [green]✓[/green] {m}")
+
+    if result.migrations_skipped:
+        console.print("[dim]Migrations skipped (already applied or not needed):[/dim]")
+        for m in result.migrations_skipped:
+            console.print(f"  [dim]○[/dim] {m}")
+
+    if result.warnings:
+        console.print("[yellow]Warnings:[/yellow]")
+        for w in result.warnings:
+            console.print(f"  [yellow]![/yellow] {w}")
+
+    if result.errors:
+        console.print("[red]Errors:[/red]")
+        for e in result.errors:
+            console.print(f"  [red]✗[/red] {e}")
+
+    console.print()
+    if result.success:
+        console.print(
+            f"[bold green]Upgrade complete![/bold green] {result.from_version} -> {result.to_version}"
+        )
+    else:
+        console.print("[bold red]Upgrade failed.[/bold red]")
+        raise typer.Exit(1)
+
+
+def list_legacy_features() -> None:
+    """List legacy worktrees blocking 0.11.0 upgrade."""
+    from specify_cli.tasks_support import find_repo_root
+    from specify_cli.upgrade.migrations.m_0_11_0_workspace_per_wp import (
+        detect_legacy_worktrees,
+    )
+
+    repo_root = find_repo_root()
+    legacy = detect_legacy_worktrees(repo_root)
+
+    if not legacy:
+        console.print("[green]✓[/green] No legacy worktrees found")
+        console.print("Project is ready for 0.11.0 upgrade")
+        return
+
+    console.print(f"[yellow]Legacy worktrees found:[/yellow] {len(legacy)}\n")
+    for worktree in legacy:
+        console.print(f"  - {worktree.name}")
+
+    console.print("\n[cyan]Action required:[/cyan]")
+    console.print("  Complete: spec-kitty merge <feature>")
+    console.print("  OR Delete: git worktree remove .worktrees/<feature>")
+
+
+__all__ = ["upgrade", "list_legacy_features"]

specify_cli/cli/commands/validate_encoding.py

@@ -0,0 +1,186 @@
+"""Encoding validation command for Spec Kitty CLI."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+import typer
+from rich.panel import Panel
+from rich.table import Table
+
+from specify_cli.acceptance import AcceptanceError, detect_feature_slug
+from specify_cli.cli.helpers import check_version_compatibility, console, get_project_root_or_exit
+from specify_cli.core.project_resolver import resolve_worktree_aware_feature_dir
+from specify_cli.tasks_support import TaskCliError, find_repo_root
+from specify_cli.text_sanitization import detect_problematic_characters, sanitize_directory, sanitize_file
+
+
+def validate_encoding(
+    feature: Optional[str] = typer.Option(None, "--feature", help="Feature slug to validate (auto-detected when omitted)"),
+    fix: bool = typer.Option(False, "--fix", help="Automatically fix encoding errors by sanitizing files"),
+    check_all: bool = typer.Option(False, "--all", help="Check all features, not just one"),
+    backup: bool = typer.Option(True, "--backup/--no-backup", help="Create .bak files before fixing"),
+) -> None:
+    """Validate and optionally fix file encoding in feature artifacts.
+
+    Scans markdown files for Windows-1252 smart quotes and other problematic
+    characters that cause UTF-8 encoding errors. Can automatically fix issues
+    by replacing problematic characters with safe alternatives.
+    """
+    try:
+        repo_root = find_repo_root()
+    except TaskCliError as exc:
+        console.print(f"[red]Error:[/red] {exc}")
+        raise typer.Exit(1)
+
+    project_root = get_project_root_or_exit(repo_root)
+    check_version_compatibility(project_root, "validate-encoding")
+
+    if check_all:
+        # Validate all features
+        kitty_specs = repo_root / "kitty-specs"
+        if not kitty_specs.exists():
+            console.print("[yellow]No kitty-specs directory found.[/yellow]")
+            raise typer.Exit(0)
+
+        feature_dirs = [d for d in kitty_specs.iterdir() if d.is_dir()]
+        if not feature_dirs:
+            console.print("[yellow]No feature directories found.[/yellow]")
+            raise typer.Exit(0)
+
+        console.print(f"[cyan]Checking encoding for {len(feature_dirs)} features...[/cyan]")
+        console.print()
+
+        total_issues = 0
+        total_fixed = 0
+
+        for feature_dir in sorted(feature_dirs):
+            issues, fixed = _validate_feature_dir(feature_dir, fix=fix, backup=backup)
+            total_issues += issues
+            total_fixed += fixed
+
+        console.print()
+        console.print(Panel(
+            f"[bold]Summary:[/bold]\n"
+            f"Total files with issues: [yellow]{total_issues}[/yellow]\n"
+            f"Total files fixed: [green]{total_fixed}[/green]",
+            title="Encoding Validation Complete",
+            border_style="cyan" if total_issues == 0 else "yellow",
+        ))
+
+        raise typer.Exit(0 if total_issues == 0 or fix else 1)
+
+    # Validate single feature
+    try:
+        feature_slug = (feature or detect_feature_slug(repo_root, cwd=Path.cwd())).strip()
+    except AcceptanceError as exc:
+        console.print(f"[red]Error:[/red] {exc}")
+        raise typer.Exit(1)
+
+    feature_dir = resolve_worktree_aware_feature_dir(repo_root, feature_slug, Path.cwd(), console)
+
+    if not feature_dir.exists():
+        console.print(f"[red]Error:[/red] Feature directory not found: {feature_dir}")
+        raise typer.Exit(1)
+
+    console.print(f"[cyan]Validating encoding for feature:[/cyan] {feature_slug}")
+    console.print()
+
+    issues, fixed = _validate_feature_dir(feature_dir, fix=fix, backup=backup)
+
+    if issues == 0:
+        console.print("[green]✓ All files are properly UTF-8 encoded![/green]")
+        raise typer.Exit(0)
+    elif fix and fixed > 0:
+        console.print()
+        console.print(f"[green]✓ Fixed {fixed} file(s) with encoding issues.[/green]")
+        if backup:
+            console.print("[dim]Backup files (.bak) were created.[/dim]")
+        raise typer.Exit(0)
+    else:
+        console.print()
+        console.print(f"[yellow]Found {issues} file(s) with encoding issues.[/yellow]")
+        console.print("[dim]Run with --fix to automatically repair these files.[/dim]")
+        raise typer.Exit(1)
+
+
+def _validate_feature_dir(feature_dir: Path, *, fix: bool, backup: bool) -> tuple[int, int]:
+    """Validate encoding for a single feature directory.
+
+    Returns:
+        Tuple of (issues_found, files_fixed)
+    """
+    console.print(f"[cyan]Checking:[/cyan] {feature_dir.name}")
+
+    # Scan all markdown files
+    results = sanitize_directory(feature_dir, pattern="**/*.md", backup=backup, dry_run=not fix)
+
+    files_with_issues = []
+    files_fixed = []
+    file_errors = []
+
+    for file_path_str, (was_modified, error) in results.items():
+        file_path = Path(file_path_str)
+        relative_path = file_path.relative_to(feature_dir) if file_path.is_relative_to(feature_dir) else file_path
+
+        if error:
+            file_errors.append((relative_path, error))
+        elif was_modified:
+            files_with_issues.append(relative_path)
+            if fix:
+                files_fixed.append(relative_path)
+
+    # Display results
+    if files_with_issues:
+        table = Table(title=f"Files with Encoding Issues: {feature_dir.name}", show_header=True)
+        table.add_column("File", style="cyan")
+        table.add_column("Status", style="yellow")
+
+        for file_path in files_with_issues:
+            status = "[green]Fixed[/green]" if fix else "[yellow]Needs Fix[/yellow]"
+            table.add_row(str(file_path), status)
+
+        console.print(table)
+
+        # Show detailed character issues for first file
+        if files_with_issues and not fix:
+            first_file = feature_dir / files_with_issues[0]
+            try:
+                # Read with fallback encoding
+                try:
+                    content = first_file.read_text(encoding="utf-8-sig")
+                except UnicodeDecodeError:
+                    content_bytes = first_file.read_bytes()
+                    for encoding in ("cp1252", "latin-1"):
+                        try:
+                            content = content_bytes.decode(encoding)
+                            break
+                        except UnicodeDecodeError:
+                            continue
+                    else:
+                        content = content_bytes.decode("utf-8", errors="replace")
+
+                issues = detect_problematic_characters(content)
+                if issues:
+                    console.print()
+                    console.print(f"[yellow]Example issues in {files_with_issues[0]}:[/yellow]")
+                    for line_num, col, char, replacement in issues[:5]:  # Show first 5
+                        console.print(
+                            f"  Line {line_num}, col {col}: '{char}' (U+{ord(char):04X}) → '{replacement}'"
+                        )
+                    if len(issues) > 5:
+                        console.print(f"  ... and {len(issues) - 5} more")
+            except Exception:
+                pass
+
+    if file_errors:
+        console.print()
+        console.print("[red]Errors encountered:[/red]")
+        for file_path, error in file_errors:
+            console.print(f"  [red]✗[/red] {file_path}: {error}")
+
+    return len(files_with_issues), len(files_fixed)
+
+
+__all__ = ["validate_encoding"]

specify_cli/cli/commands/validate_tasks.py

@@ -0,0 +1,186 @@
+"""Task metadata validation command for Spec Kitty CLI."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Optional
+
+import typer
+from rich.panel import Panel
+from rich.table import Table
+
+from specify_cli.acceptance import AcceptanceError, detect_feature_slug
+from specify_cli.cli.helpers import check_version_compatibility, console, get_project_root_or_exit
+from specify_cli.core.project_resolver import resolve_worktree_aware_feature_dir
+from specify_cli.task_metadata_validation import (
+    detect_lane_mismatch,
+    repair_lane_mismatch,
+    scan_all_tasks_for_mismatches,
+    validate_task_metadata,
+)
+from specify_cli.tasks_support import TaskCliError, find_repo_root
+
+
+def validate_tasks(
+    feature: Optional[str] = typer.Option(
+        None, "--feature", help="Feature slug to validate (auto-detected when omitted)"
+    ),
+    fix: bool = typer.Option(False, "--fix", help="Automatically repair metadata inconsistencies"),
+    check_all: bool = typer.Option(False, "--all", help="Check all features, not just one"),
+    agent: Optional[str] = typer.Option(None, "--agent", help="Agent name for activity log"),
+    shell_pid: Optional[str] = typer.Option(None, "--shell-pid", help="Shell PID for activity log"),
+) -> None:
+    """Validate and optionally fix task metadata inconsistencies.
+
+    Detects when work package frontmatter doesn't match file location:
+    - File in tasks/for_review/ but lane: "planned" in frontmatter
+    - File in tasks/doing/ but lane: "done" in frontmatter
+    - etc.
+
+    Can automatically fix by updating frontmatter to match directory.
+    """
+    try:
+        repo_root = find_repo_root()
+    except TaskCliError as exc:
+        console.print(f"[red]Error:[/red] {exc}")
+        raise typer.Exit(1)
+
+    project_root = get_project_root_or_exit(repo_root)
+    check_version_compatibility(project_root, "validate-tasks")
+
+    # Get agent and shell_pid from environment if not provided
+    if not agent:
+        agent = os.environ.get("SPEC_KITTY_AGENT", "system")
+    if not shell_pid:
+        shell_pid = str(os.getpid())
+
+    if check_all:
+        # Validate all features
+        kitty_specs = repo_root / "kitty-specs"
+        worktrees = repo_root / ".worktrees"
+
+        feature_dirs = []
+        if kitty_specs.exists():
+            feature_dirs.extend([d for d in kitty_specs.iterdir() if d.is_dir()])
+        if worktrees.exists():
+            for wt_dir in worktrees.iterdir():
+                if wt_dir.is_dir():
+                    wt_specs = wt_dir / "kitty-specs"
+                    if wt_specs.exists():
+                        feature_dirs.extend([d for d in wt_specs.iterdir() if d.is_dir()])
+
+        if not feature_dirs:
+            console.print("[yellow]No feature directories found.[/yellow]")
+            raise typer.Exit(0)
+
+        console.print(f"[cyan]Checking task metadata for {len(feature_dirs)} features...[/cyan]")
+        console.print()
+
+        total_mismatches = 0
+        total_fixed = 0
+
+        for feature_dir in sorted(feature_dirs, key=lambda d: d.name):
+            mismatches, fixed = _validate_feature_tasks(
+                feature_dir, fix=fix, agent=agent, shell_pid=shell_pid
+            )
+            total_mismatches += mismatches
+            total_fixed += fixed
+
+        console.print()
+        console.print(
+            Panel(
+                f"[bold]Summary:[/bold]\n"
+                f"Total mismatches found: [yellow]{total_mismatches}[/yellow]\n"
+                f"Total mismatches fixed: [green]{total_fixed}[/green]",
+                title="Task Metadata Validation Complete",
+                border_style="cyan" if total_mismatches == 0 else "yellow",
+            )
+        )
+
+        raise typer.Exit(0 if total_mismatches == 0 or fix else 1)
+
+    # Validate single feature
+    try:
+        feature_slug = (feature or detect_feature_slug(repo_root, cwd=Path.cwd())).strip()
+    except AcceptanceError as exc:
+        console.print(f"[red]Error:[/red] {exc}")
+        raise typer.Exit(1)
+
+    feature_dir = resolve_worktree_aware_feature_dir(repo_root, feature_slug, Path.cwd(), console)
+
+    if not feature_dir.exists():
+        console.print(f"[red]Error:[/red] Feature directory not found: {feature_dir}")
+        raise typer.Exit(1)
+
+    console.print(f"[cyan]Validating task metadata for feature:[/cyan] {feature_slug}")
+    console.print()
+
+    mismatches, fixed = _validate_feature_tasks(
+        feature_dir, fix=fix, agent=agent, shell_pid=shell_pid
+    )
+
+    if mismatches == 0:
+        console.print("[green]✓ All task metadata is consistent![/green]")
+        raise typer.Exit(0)
+    elif fix and fixed > 0:
+        console.print()
+        console.print(f"[green]✓ Fixed {fixed} metadata mismatch(es).[/green]")
+        raise typer.Exit(0)
+    else:
+        console.print()
+        console.print(f"[yellow]Found {mismatches} metadata mismatch(es).[/yellow]")
+        console.print("[dim]Run with --fix to automatically repair these mismatches.[/dim]")
+        raise typer.Exit(1)
+
+
+def _validate_feature_tasks(
+    feature_dir: Path, *, fix: bool, agent: str, shell_pid: str
+) -> tuple[int, int]:
+    """Validate task metadata for a single feature directory.
+
+    Returns:
+        Tuple of (mismatches_found, mismatches_fixed)
+    """
+    console.print(f"[cyan]Checking:[/cyan] {feature_dir.name}")
+
+    mismatches_dict = scan_all_tasks_for_mismatches(feature_dir)
+
+    if not mismatches_dict:
+        console.print(f"  [green]✓[/green] No metadata mismatches")
+        return 0, 0
+
+    # Display mismatches in a table
+    table = Table(title=f"Task Metadata Mismatches: {feature_dir.name}", show_header=True)
+    table.add_column("File", style="cyan")
+    table.add_column("Expected Lane", style="green")
+    table.add_column("Actual Lane", style="yellow")
+    table.add_column("Status", style="white")
+
+    fixed_count = 0
+    for file_path, (_, expected, actual) in mismatches_dict.items():
+        full_path = feature_dir / file_path
+
+        status = "[yellow]Needs Fix[/yellow]"
+        if fix:
+            was_repaired, error = repair_lane_mismatch(
+                full_path, agent=agent, shell_pid=shell_pid, add_history=True, dry_run=False
+            )
+            if was_repaired:
+                status = "[green]Fixed[/green]"
+                fixed_count += 1
+            elif error:
+                status = f"[red]Error: {error}[/red]"
+
+        table.add_row(file_path, expected or "?", actual or "?", status)
+
+    console.print(table)
+
+    if fix:
+        console.print()
+        console.print(f"  [green]Fixed {fixed_count} of {len(mismatches_dict)} mismatches[/green]")
+
+    return len(mismatches_dict), fixed_count
+
+
+__all__ = ["validate_tasks"]