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

specify_cli/cli/commands/repair.py

@@ -0,0 +1,175 @@
+"""Repair command to fix broken templates and diagnose worktrees."""
+
+import typer
+from pathlib import Path
+from rich.console import Console
+from typing import Optional
+
+from specify_cli.upgrade.migrations.m_0_10_9_repair_templates import RepairTemplatesMigration
+from specify_cli.core.paths import locate_project_root, get_main_repo_root, is_worktree_context
+
+app = typer.Typer()
+console = Console()
+
+
+@app.command()
+def repair(
+    project_path: Path = typer.Option(
+        Path.cwd(),
+        "--project-path",
+        "-p",
+        help="Path to project to repair"
+    ),
+    dry_run: bool = typer.Option(
+        False,
+        "--dry-run",
+        help="Show what would be changed without making changes"
+    )
+):
+    """Repair broken templates caused by v0.10.0-0.10.8 bundling bug.
+
+    This command fixes templates that reference non-existent bash scripts
+    by regenerating them from the correct source. Run this if you see errors
+    like "scripts/bash/check-prerequisites.sh: No such file or directory".
+    """
+    console.print("[bold]Spec Kitty Template Repair[/bold]")
+    console.print()
+
+    migration = RepairTemplatesMigration()
+
+    # Detect if repair needed
+    needs_repair = migration.detect(project_path)
+
+    if not needs_repair:
+        console.print("[green]✓ No broken templates detected - project is healthy![/green]")
+        return
+
+    console.print("[yellow]⚠ Broken templates detected[/yellow]")
+    console.print("Found bash script references in slash commands")
+    console.print()
+
+    if dry_run:
+        console.print("[cyan]Dry run mode - showing what would be changed:[/cyan]")
+
+    # Apply repair
+    result = migration.apply(project_path, dry_run=dry_run)
+
+    if result.success:
+        console.print()
+        console.print("[green]✓ Repair completed successfully[/green]")
+        for change in result.changes_made:
+            console.print(f"  • {change}")
+    else:
+        console.print()
+        console.print("[red]✗ Repair failed[/red]")
+        for error in result.errors:
+            console.print(f"  • [red]{error}[/red]")
+
+    if result.warnings:
+        console.print()
+        console.print("[yellow]Warnings:[/yellow]")
+        for warning in result.warnings:
+            console.print(f"  • {warning}")
+
+
+@app.command(name="worktree")
+def repair_worktree(
+    all_worktrees: bool = typer.Option(
+        False,
+        "--all",
+        help="Check all worktrees in .worktrees/ directory"
+    ),
+    worktree_path: Optional[Path] = typer.Argument(
+        None,
+        help="Specific worktree path to check (defaults to current directory if in a worktree)"
+    ),
+):
+    """Diagnose worktree kitty-specs/ status.
+
+    This command checks if worktrees have kitty-specs/ directories and explains
+    how WP operations work:
+
+    - WP lane changes (move-task) ALWAYS use main repo's kitty-specs/
+    - Research artifacts can be added to worktree's kitty-specs/
+    - Stale WP files in worktrees don't affect lane operations
+
+    Examples:
+        spec-kitty repair worktree           # Check current worktree
+        spec-kitty repair worktree --all     # Check all worktrees
+    """
+    console.print("[bold]Spec Kitty Worktree Diagnostics[/bold]")
+    console.print()
+
+    # Find project root
+    cwd = Path.cwd().resolve()
+    repo_root = locate_project_root(cwd)
+
+    if repo_root is None:
+        console.print("[red]Error:[/red] Could not locate project root")
+        raise typer.Exit(1)
+
+    main_root = get_main_repo_root(repo_root)
+
+    worktrees_to_check: list[Path] = []
+
+    if all_worktrees:
+        # Check all worktrees in .worktrees/
+        worktrees_dir = main_root / ".worktrees"
+        if worktrees_dir.exists():
+            for item in worktrees_dir.iterdir():
+                if item.is_dir() and (item / ".git").exists():
+                    worktrees_to_check.append(item)
+        if not worktrees_to_check:
+            console.print("[yellow]No worktrees found in .worktrees/[/yellow]")
+            return
+    elif worktree_path:
+        # Use specified path
+        worktree_path = worktree_path.resolve()
+        if not worktree_path.exists():
+            console.print(f"[red]Error:[/red] Worktree path does not exist: {worktree_path}")
+            raise typer.Exit(1)
+        worktrees_to_check.append(worktree_path)
+    else:
+        # Try current directory
+        if is_worktree_context(cwd):
+            # Find the worktree root
+            current = cwd
+            while current != current.parent:
+                if (current / ".git").exists():
+                    worktrees_to_check.append(current)
+                    break
+                current = current.parent
+            if not worktrees_to_check:
+                console.print("[red]Error:[/red] Could not find worktree root")
+                raise typer.Exit(1)
+        else:
+            console.print("[yellow]Not in a worktree. Use --all to check all worktrees.[/yellow]")
+            return
+
+    console.print(f"Found {len(worktrees_to_check)} worktree(s) to check")
+    console.print()
+
+    for wt_path in worktrees_to_check:
+        has_kitty_specs = (wt_path / "kitty-specs").exists()
+        has_tasks = (wt_path / "kitty-specs").exists() and any(
+            (wt_path / "kitty-specs").rglob("tasks/*.md")
+        )
+
+        console.print(f"[bold]{wt_path.name}[/bold]")
+
+        if not has_kitty_specs:
+            console.print("  [dim]No kitty-specs/ directory[/dim]")
+        else:
+            console.print(f"  kitty-specs/: [green]present[/green]")
+            if has_tasks:
+                console.print(f"  tasks/*.md: [yellow]present (stale copies)[/yellow]")
+            else:
+                console.print(f"  tasks/*.md: [dim]none[/dim]")
+
+    console.print()
+    console.print("[bold cyan]How WP operations work:[/bold cyan]")
+    console.print("  • [green]move-task[/green] always updates [bold]main repo's[/bold] kitty-specs/")
+    console.print("  • Research artifacts can be added to worktree's kitty-specs/")
+    console.print("  • Stale WP files in worktrees are [dim]ignored[/dim] by lane operations")
+    console.print()
+    console.print("[dim]No repair needed - this is informational only.[/dim]")

specify_cli/cli/commands/research.py

@@ -0,0 +1,165 @@
+"""Research command implementation for Spec Kitty CLI."""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+from typing import Optional
+
+import typer
+from rich.panel import Panel
+
+from specify_cli.acceptance import AcceptanceError, detect_feature_slug
+from specify_cli.cli import StepTracker
+from specify_cli.cli.helpers import check_version_compatibility, console, get_project_root_or_exit, show_banner
+from specify_cli.core import MISSION_CHOICES
+from specify_cli.core.project_resolver import resolve_template_path, resolve_worktree_aware_feature_dir
+from specify_cli.mission import get_feature_mission_key
+from specify_cli.plan_validation import PlanValidationError, validate_plan_filled
+from specify_cli.tasks_support import TaskCliError, find_repo_root
+
+
+def research(
+    feature: Optional[str] = typer.Option(None, "--feature", help="Feature slug to target (auto-detected when omitted)"),
+    force: bool = typer.Option(False, "--force", help="Overwrite existing research artifacts"),
+) -> None:
+    """Execute Phase 0 research workflow to scaffold artifacts."""
+
+    show_banner()
+
+    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, "research")
+
+    tracker = StepTracker("Research Phase Setup")
+    tracker.add("project", "Locate project root")
+    tracker.add("feature", "Resolve feature directory")
+    tracker.add("research-md", "Ensure research.md")
+    tracker.add("data-model", "Ensure data-model.md")
+    tracker.add("research-csv", "Ensure research CSV stubs")
+    tracker.add("summary", "Summarize outputs")
+    console.print()
+
+    tracker.start("project")
+    tracker.complete("project", str(project_root))
+
+    tracker.start("feature")
+    try:
+        feature_slug = (feature or detect_feature_slug(repo_root, cwd=Path.cwd())).strip()
+    except AcceptanceError as exc:
+        tracker.error("feature", str(exc))
+        console.print(tracker.render())
+        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)
+    feature_dir.mkdir(parents=True, exist_ok=True)
+
+    # Get mission from feature's meta.json (not project-level default)
+    mission_key = get_feature_mission_key(feature_dir)
+    mission_display = MISSION_CHOICES.get(mission_key, mission_key)
+    tracker.complete("feature", f"{feature_dir} ({mission_display})")
+
+    # Validate that plan.md has been filled out before proceeding
+    plan_path = feature_dir / "plan.md"
+    try:
+        validate_plan_filled(plan_path, feature_slug=feature_slug, strict=True)
+    except PlanValidationError as exc:
+        console.print(tracker.render())
+        console.print()
+        console.print(f"[red]Error:[/red] {exc}")
+        console.print()
+        console.print("[yellow]Next steps:[/yellow]")
+        console.print("  1. Run [cyan]/spec-kitty.plan[/cyan] to fill in the technical architecture")
+        console.print("  2. Complete all [FEATURE], [DATE], and technical context placeholders")
+        console.print("  3. Remove [REMOVE IF UNUSED] sections and choose your project structure")
+        console.print("  4. Then run [cyan]/spec-kitty.research[/cyan] again")
+        raise typer.Exit(1)
+
+    created_paths: list[Path] = []
+
+    def _copy_asset(step_key: str, label: str, relative_path: Path, template_name: Path) -> None:
+        tracker.start(step_key)
+        dest_path = feature_dir / relative_path
+        template_path = resolve_template_path(project_root, mission_key, template_name)
+
+        dest_path.parent.mkdir(parents=True, exist_ok=True)
+        try:
+            if dest_path.exists() and not force:
+                created_paths.append(dest_path)
+                return
+            if template_path and template_path.is_file():
+                shutil.copy2(template_path, dest_path)
+            else:
+                if dest_path.exists():
+                    dest_path.unlink()
+                dest_path.touch()
+            created_paths.append(dest_path)
+            tracker.complete(step_key, label)
+        except Exception as exc:  # pragma: no cover - surfaces filesystem errors
+            tracker.error(step_key, str(exc))
+            console.print(tracker.render())
+            raise typer.Exit(1)
+
+    _copy_asset("research-md", "research.md ready", Path("research.md"), Path("research.md"))
+    _copy_asset("data-model", "data-model.md ready", Path("data-model.md"), Path("data-model.md"))
+
+    tracker.start("research-csv")
+    csv_targets = [
+        (Path("research") / "evidence-log.csv", Path("research") / "evidence-log.csv"),
+        (Path("research") / "source-register.csv", Path("research") / "source-register.csv"),
+    ]
+    csv_errors: list[str] = []
+    for dest_rel, template_rel in csv_targets:
+        dest_path = feature_dir / dest_rel
+        template_path = resolve_template_path(project_root, mission_key, template_rel)
+        dest_path.parent.mkdir(parents=True, exist_ok=True)
+        try:
+            if dest_path.exists() and not force:
+                created_paths.append(dest_path)
+                continue
+            if template_path and template_path.is_file():
+                shutil.copy2(template_path, dest_path)
+            else:
+                if dest_path.exists():
+                    dest_path.unlink()
+                dest_path.touch()
+            created_paths.append(dest_path)
+        except Exception as exc:  # pragma: no cover
+            csv_errors.append(f"{dest_rel}: {exc}")
+
+    if csv_errors:
+        tracker.error("research-csv", "; ".join(csv_errors))
+        console.print(tracker.render())
+        raise typer.Exit(1)
+    else:
+        tracker.complete("research-csv", "CSV templates ready")
+
+    tracker.start("summary")
+    tracker.complete("summary", f"{len(created_paths)} artifacts ready")
+
+    console.print(tracker.render())
+
+    relative_paths = [
+        str(path.relative_to(feature_dir)) if path.is_relative_to(feature_dir) else str(path)
+        for path in created_paths
+    ]
+    summary_lines = "\n".join(f"- [cyan]{rel}[/cyan]" for rel in sorted(set(relative_paths)))
+    console.print()
+    console.print(
+        Panel(
+            summary_lines or "No artifacts were created (existing files kept).",
+            title="Research Artifacts",
+            border_style="cyan",
+            padding=(1, 2),
+        )
+    )
+    console.print()
+
+
+__all__ = ["research"]

specify_cli/cli/commands/sync.py

@@ -0,0 +1,364 @@
+"""Sync command - synchronize workspace with upstream changes.
+
+This command updates a workspace with changes from its base branch or parent.
+For git workspaces, this performs a rebase. For jj workspaces, this updates
+the workspace revision.
+
+Key difference:
+- git: Sync may fail on conflicts (must be resolved before continuing)
+- jj: Sync always succeeds (conflicts are stored and can be resolved later)
+"""
+
+from __future__ import annotations
+
+import re
+import subprocess
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+from specify_cli.core.vcs import (
+    ChangeInfo,
+    ConflictInfo,
+    SyncResult,
+    SyncStatus,
+    VCSBackend,
+    get_vcs,
+)
+
+console = Console()
+
+
+def _detect_workspace_context() -> tuple[Path, str | None]:
+    """Detect current workspace and feature context.
+
+    Returns:
+        Tuple of (workspace_path, feature_slug)
+        If not in a workspace, returns (cwd, None)
+    """
+    cwd = Path.cwd()
+
+    # Check if we're in a .worktrees directory
+    parts = cwd.parts
+    for i, part in enumerate(parts):
+        if part == ".worktrees" and i + 1 < len(parts):
+            # Found a worktree path like: /repo/.worktrees/010-feature-WP01
+            workspace_name = parts[i + 1]
+            # Extract feature slug from workspace name (###-feature-WP##)
+            match = re.match(r"^(\d{3}-[a-zA-Z0-9-]+)-WP\d+$", workspace_name)
+            if match:
+                return cwd, match.group(1)
+
+    # Try to detect from git branch
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "--abbrev-ref", "HEAD"],
+            capture_output=True,
+            text=True,
+            check=False,
+            cwd=cwd,
+        )
+        if result.returncode == 0:
+            branch_name = result.stdout.strip()
+            # Check if branch matches WP pattern (###-feature-WP##)
+            match = re.match(r"^(\d{3}-[a-zA-Z0-9-]+)-WP\d+$", branch_name)
+            if match:
+                return cwd, match.group(1)
+    except (FileNotFoundError, OSError):
+        pass
+
+    # Not in a recognized workspace
+    return cwd, None
+
+
+def _display_changes_integrated(changes: list[ChangeInfo]) -> None:
+    """Display changes that were integrated during sync."""
+    if not changes:
+        return
+
+    console.print(f"\n[cyan]Changes integrated ({len(changes)}):[/cyan]")
+    for change in changes[:5]:  # Show first 5 changes
+        short_id = change.commit_id[:7] if change.commit_id else "unknown"
+        # Truncate message to 50 chars
+        msg = change.message[:50] + "..." if len(change.message) > 50 else change.message
+        console.print(f"  • [dim]{short_id}[/dim] {msg}")
+
+    if len(changes) > 5:
+        console.print(f"  [dim]... and {len(changes) - 5} more[/dim]")
+
+
+def _display_conflicts(conflicts: list[ConflictInfo]) -> None:
+    """Display conflicts with actionable details.
+
+    Shows:
+    - File path
+    - Line ranges (if available)
+    - Conflict type
+    - Resolution hints
+    """
+    if not conflicts:
+        return
+
+    console.print(f"\n[yellow]Conflicts ({len(conflicts)} files):[/yellow]")
+
+    # Create a table for better formatting
+    table = Table(show_header=True, header_style="bold yellow", show_lines=False)
+    table.add_column("File", style="cyan")
+    table.add_column("Type", style="dim")
+    table.add_column("Lines", style="dim")
+
+    for conflict in conflicts:
+        # Format line ranges
+        if conflict.line_ranges:
+            lines = ", ".join(f"{start}-{end}" for start, end in conflict.line_ranges)
+        else:
+            lines = "entire file"
+
+        table.add_row(
+            str(conflict.file_path),
+            conflict.conflict_type.value,
+            lines,
+        )
+
+    console.print(table)
+
+    # Show resolution hints
+    console.print("\n[dim]To resolve conflicts:[/dim]")
+    console.print("[dim]  1. Edit the conflicted files to resolve markers[/dim]")
+    console.print("[dim]  2. Continue your work (jj) or commit resolution (git)[/dim]")
+
+
+def _git_repair(workspace_path: Path) -> bool:
+    """Attempt git workspace recovery.
+
+    This is a best-effort recovery that tries:
+    1. Abort any in-progress rebase/merge
+    2. Reset to HEAD
+
+    Returns:
+        True if recovery succeeded, False otherwise
+
+    Note: This may lose uncommitted work.
+    """
+    try:
+        # First, try to abort any in-progress operations
+        for abort_cmd in [
+            ["git", "rebase", "--abort"],
+            ["git", "merge", "--abort"],
+            ["git", "cherry-pick", "--abort"],
+        ]:
+            subprocess.run(
+                abort_cmd,
+                cwd=workspace_path,
+                capture_output=True,
+                check=False,
+                timeout=10,
+            )
+
+        # Reset to HEAD (keeping changes in working tree)
+        result = subprocess.run(
+            ["git", "reset", "--mixed", "HEAD"],
+            cwd=workspace_path,
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=30,
+        )
+
+        return result.returncode == 0
+
+    except (subprocess.TimeoutExpired, OSError):
+        return False
+
+
+def _jj_repair(workspace_path: Path) -> bool:
+    """Attempt jj workspace recovery via operation undo.
+
+    Jujutsu has much better recovery capabilities via the operation log.
+    This function tries to undo the last operation.
+
+    Returns:
+        True if recovery succeeded, False otherwise
+    """
+    try:
+        # Try to undo the last operation
+        result = subprocess.run(
+            ["jj", "undo"],
+            cwd=workspace_path,
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=30,
+        )
+
+        if result.returncode == 0:
+            return True
+
+        # If undo fails, try to update the workspace
+        result = subprocess.run(
+            ["jj", "workspace", "update-stale"],
+            cwd=workspace_path,
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=30,
+        )
+
+        return result.returncode == 0
+
+    except (subprocess.TimeoutExpired, OSError):
+        return False
+
+
+def sync(
+    repair: bool = typer.Option(
+        False,
+        "--repair",
+        "-r",
+        help="Attempt workspace recovery (may lose uncommitted work)",
+    ),
+    verbose: bool = typer.Option(
+        False,
+        "--verbose",
+        "-v",
+        help="Show detailed sync output",
+    ),
+) -> None:
+    """Synchronize workspace with upstream changes.
+
+    Updates the current workspace with changes from its base branch or parent.
+    This is equivalent to:
+    - git: `git rebase <base-branch>`
+    - jj: `jj workspace update-stale` + auto-rebase
+
+    Key difference between VCS backends:
+    - git: Sync may FAIL on conflicts (must resolve before continuing)
+    - jj: Sync always SUCCEEDS (conflicts stored, resolve later)
+
+    Examples:
+        # Sync current workspace
+        spec-kitty sync
+
+        # Sync with verbose output
+        spec-kitty sync --verbose
+
+        # Attempt recovery from broken state
+        spec-kitty sync --repair
+    """
+    console.print()
+
+    # Detect workspace context
+    workspace_path, feature_slug = _detect_workspace_context()
+
+    if feature_slug is None:
+        console.print("[yellow]⚠ Not in a recognized workspace[/yellow]")
+        console.print("Run this command from a worktree directory:")
+        console.print("  cd .worktrees/<feature>-WP##/")
+        raise typer.Exit(1)
+
+    console.print(f"[cyan]Workspace:[/cyan] {workspace_path.name}")
+
+    # Get VCS implementation
+    try:
+        vcs = get_vcs(workspace_path)
+    except Exception as e:
+        console.print(f"[red]Error:[/red] Failed to detect VCS: {e}")
+        raise typer.Exit(1)
+
+    console.print(f"[cyan]Backend:[/cyan] git")
+    console.print()
+
+    # Handle repair mode
+    if repair:
+        console.print("[yellow]Attempting workspace recovery...[/yellow]")
+        console.print("[dim]Note: This may lose uncommitted work[/dim]")
+        console.print()
+
+        if vcs.backend == VCSBackend.JUJUTSU:
+            success = _jj_repair(workspace_path)
+        else:
+            success = _git_repair(workspace_path)
+
+        if success:
+            console.print("[green]✓ Recovery successful[/green]")
+            console.print("Workspace state has been reset.")
+        else:
+            console.print("[red]✗ Recovery failed[/red]")
+            console.print("Manual intervention may be required.")
+            console.print()
+            if vcs.backend == VCSBackend.GIT:
+                console.print("[dim]Try these commands manually:[/dim]")
+                console.print("  git status")
+                console.print("  git rebase --abort")
+                console.print("  git reset --hard HEAD")
+            else:
+                console.print("[dim]Try these commands manually:[/dim]")
+                console.print("  jj status")
+                console.print("  jj op log")
+                console.print("  jj undo")
+            raise typer.Exit(1)
+
+        return
+
+    # Perform sync
+    console.print("[cyan]Syncing workspace...[/cyan]")
+
+    result: SyncResult = vcs.sync_workspace(workspace_path)
+
+    # Display result based on status
+    if result.status == SyncStatus.UP_TO_DATE:
+        console.print("\n[green]✓ Already up to date[/green]")
+        if result.message:
+            console.print(f"[dim]{result.message}[/dim]")
+
+    elif result.status == SyncStatus.SYNCED:
+        stats_parts = []
+        if result.files_updated > 0:
+            stats_parts.append(f"{result.files_updated} updated")
+        if result.files_added > 0:
+            stats_parts.append(f"{result.files_added} added")
+        if result.files_deleted > 0:
+            stats_parts.append(f"{result.files_deleted} deleted")
+
+        stats = ", ".join(stats_parts) if stats_parts else "no file changes"
+        console.print(f"\n[green]✓ Synced[/green] - {stats}")
+
+        if verbose:
+            _display_changes_integrated(result.changes_integrated)
+
+        if result.message:
+            console.print(f"[dim]{result.message}[/dim]")
+
+    elif result.status == SyncStatus.CONFLICTS:
+        # jj: This means sync succeeded but there are conflicts to resolve
+        console.print("\n[yellow]⚠ Synced with conflicts[/yellow]")
+
+        if vcs.backend == VCSBackend.JUJUTSU:
+            console.print("[dim]Conflicts are stored in the commit.[/dim]")
+            console.print("[dim]You can continue working and resolve later.[/dim]")
+        else:
+            console.print("[dim]You must resolve conflicts before continuing.[/dim]")
+
+        _display_conflicts(result.conflicts)
+
+        if verbose:
+            _display_changes_integrated(result.changes_integrated)
+
+    elif result.status == SyncStatus.FAILED:
+        console.print(f"\n[red]✗ Sync failed[/red]")
+        if result.message:
+            console.print(f"[dim]{result.message}[/dim]")
+
+        # Show conflicts if any
+        if result.conflicts:
+            _display_conflicts(result.conflicts)
+
+        console.print()
+        console.print("[dim]Try:[/dim]")
+        console.print("  spec-kitty sync --repair")
+        raise typer.Exit(1)
+
+    console.print()