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

specify_cli/core/project_resolver.py

@@ -0,0 +1,110 @@
+"""Project path resolution helpers for Spec Kitty."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Optional
+
+from rich.console import Console
+
+from specify_cli.core.config import DEFAULT_MISSION_KEY
+
+ConsoleType = Console | None
+
+
+def _resolve_console(console: ConsoleType) -> Console:
+    return console if console is not None else Console()
+
+
+def locate_project_root(start: Path | None = None) -> Optional[Path]:
+    """Walk upwards from *start* (or CWD) to find the directory that owns .kittify."""
+    current = (start or Path.cwd()).resolve()
+    for candidate in [current, *current.parents]:
+        if (candidate / ".kittify").is_dir():
+            return candidate
+    return None
+
+
+def resolve_template_path(project_root: Path, mission_key: str, template_subpath: str | Path) -> Optional[Path]:
+    """Resolve a template path, preferring mission overrides before global templates."""
+    subpath = Path(template_subpath)
+    candidates = [
+        project_root / ".kittify" / "missions" / mission_key / "templates" / subpath,
+        project_root / ".kittify" / "templates" / subpath,
+        project_root / "templates" / subpath,
+    ]
+    for candidate in candidates:
+        if candidate.exists():
+            return candidate
+    return None
+
+
+def resolve_worktree_aware_feature_dir(
+    repo_root: Path,
+    feature_slug: str,
+    cwd: Path | None = None,
+    console: ConsoleType = None,
+) -> Path:
+    """Resolve the correct feature directory, preferring worktree locations when available."""
+    resolved_console = _resolve_console(console)
+    current_dir = (cwd or Path.cwd()).resolve()
+
+    parts = current_dir.parts
+    for idx, part in enumerate(parts):
+        if part == ".worktrees" and idx + 1 < len(parts) and parts[idx + 1] == feature_slug:
+            worktree_root = Path(*parts[: idx + 2])
+            feature_dir = worktree_root / "kitty-specs" / feature_slug
+            resolved_console.print(f"[green]✓[/green] Using worktree location: {feature_dir}")
+            return feature_dir
+
+    worktree_path = repo_root / ".worktrees" / feature_slug
+    if worktree_path.exists():
+        feature_dir = worktree_path / "kitty-specs" / feature_slug
+        resolved_console.print(f"[green]✓[/green] Found worktree, using: {feature_dir}")
+        resolved_console.print(f"[yellow]Tip:[/yellow] Run commands from {worktree_path} for better isolation")
+        return feature_dir
+
+    feature_dir = repo_root / "kitty-specs" / feature_slug
+    resolved_console.print(f"[yellow]⚠[/yellow] No worktree found, using root location: {feature_dir}")
+    resolved_console.print(
+        f"[yellow]Tip:[/yellow] Consider creating a worktree with: git worktree add .worktrees/{feature_slug} {feature_slug}"
+    )
+    return feature_dir
+
+
+def get_active_mission_key(project_path: Path) -> str:
+    """Return the mission key stored in .kittify/active-mission, falling back to default."""
+    active_path = project_path / ".kittify" / "active-mission"
+    if not active_path.exists():
+        return DEFAULT_MISSION_KEY
+
+    if active_path.is_symlink():
+        try:
+            target = Path(os.readlink(active_path))
+            key = target.name
+            if key:
+                return key
+        except OSError:
+            pass
+        resolved = active_path.resolve()
+        if resolved.parent.name == "missions":
+            return resolved.name
+
+    if active_path.is_file():
+        try:
+            key = active_path.read_text(encoding="utf-8-sig").strip()
+            if key:
+                return key
+        except OSError:
+            pass
+
+    return DEFAULT_MISSION_KEY
+
+
+__all__ = [
+    "get_active_mission_key",
+    "locate_project_root",
+    "resolve_template_path",
+    "resolve_worktree_aware_feature_dir",
+]

specify_cli/core/stale_detection.py

@@ -0,0 +1,263 @@
+"""
+Stale Work Package Detection
+============================
+
+Detects work packages that are in "doing" lane but have no recent VCS activity,
+indicating the agent may have stopped without transitioning the WP.
+
+Uses git/jj commit timestamps as a "heartbeat" - if no commits for a threshold
+period, the WP is considered stale.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+
+from specify_cli.core.vcs import get_vcs, VCSError
+
+
+@dataclass
+class StaleCheckResult:
+    """Result of checking a work package for staleness."""
+
+    wp_id: str
+    is_stale: bool
+    last_commit_time: datetime | None
+    minutes_since_commit: float | None
+    worktree_exists: bool
+    error: str | None = None
+
+
+def get_last_meaningful_commit_time(worktree_path: Path) -> tuple[datetime | None, bool]:
+    """
+    Get the timestamp of the most recent meaningful commit in a worktree.
+
+    A "meaningful" commit is one made ON THIS BRANCH since it diverged from main.
+    This prevents false staleness when a worktree is just created but no commits
+    have been made yet (HEAD points to parent branch's old commit).
+
+    For worktrees, we always use git to check the branch-specific history,
+    even in jj colocated repos. This is because:
+    - jj's shared history includes commits from ALL workspaces
+    - jj continuously auto-snapshots the working copy
+    - We need the last commit on THIS worktree's branch, not the shared history
+
+    Args:
+        worktree_path: Path to the worktree
+
+    Returns:
+        Tuple of (datetime of last commit on this branch, has_own_commits).
+        has_own_commits is False if the branch has no commits since diverging from main.
+    """
+    import subprocess
+
+    if not worktree_path.exists():
+        return None, False
+
+    try:
+        # First, check if this branch has any commits since diverging from main
+        # This prevents false staleness when worktree was just created
+        merge_base_result = subprocess.run(
+            ["git", "merge-base", "HEAD", "main"],
+            cwd=worktree_path,
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+
+        if merge_base_result.returncode == 0:
+            merge_base = merge_base_result.stdout.strip()
+
+            # Count commits on this branch since the merge base
+            count_result = subprocess.run(
+                ["git", "rev-list", "--count", f"{merge_base}..HEAD"],
+                cwd=worktree_path,
+                capture_output=True,
+                text=True,
+                timeout=10,
+            )
+
+            if count_result.returncode == 0:
+                commit_count = int(count_result.stdout.strip())
+                if commit_count == 0:
+                    # No commits on this branch yet - worktree just created
+                    # Don't flag as stale since agent just started
+                    return None, False
+
+        # Get the last commit time on this branch
+        result = subprocess.run(
+            ["git", "log", "-1", "--format=%cI"],
+            cwd=worktree_path,
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+
+        if result.returncode != 0 or not result.stdout.strip():
+            return None, False
+
+        # Parse ISO format timestamp
+        timestamp_str = result.stdout.strip()
+        return datetime.fromisoformat(timestamp_str), True
+
+    except subprocess.TimeoutExpired:
+        return None, False
+    except Exception:
+        return None, False
+
+
+def check_wp_staleness(
+    wp_id: str,
+    worktree_path: Path,
+    threshold_minutes: int = 10,
+) -> StaleCheckResult:
+    """
+    Check if a work package is stale based on VCS activity.
+
+    A WP is considered stale if:
+    - Its worktree exists
+    - The branch has commits since diverging from main (agent has done work)
+    - The last commit is older than threshold_minutes
+
+    A WP with a worktree but NO commits since diverging is NOT stale - the agent
+    just started and hasn't committed yet.
+
+    Args:
+        wp_id: Work package ID (e.g., "WP01")
+        worktree_path: Path to the WP's worktree
+        threshold_minutes: Minutes of inactivity before considered stale
+
+    Returns:
+        StaleCheckResult with staleness status
+    """
+    if not worktree_path.exists():
+        return StaleCheckResult(
+            wp_id=wp_id,
+            is_stale=False,
+            last_commit_time=None,
+            minutes_since_commit=None,
+            worktree_exists=False,
+        )
+
+    try:
+        last_commit, has_own_commits = get_last_meaningful_commit_time(worktree_path)
+
+        if last_commit is None:
+            # Can't determine commit time, or no commits on this branch yet
+            # If no commits yet (has_own_commits=False), agent just started - not stale
+            return StaleCheckResult(
+                wp_id=wp_id,
+                is_stale=False,
+                last_commit_time=None,
+                minutes_since_commit=None,
+                worktree_exists=True,
+                error=None if not has_own_commits else "Could not determine last commit time",
+            )
+
+        now = datetime.now(timezone.utc)
+        # Ensure last_commit is timezone-aware
+        if last_commit.tzinfo is None:
+            last_commit = last_commit.replace(tzinfo=timezone.utc)
+
+        delta = now - last_commit
+        minutes_since = delta.total_seconds() / 60
+
+        is_stale = minutes_since > threshold_minutes
+
+        return StaleCheckResult(
+            wp_id=wp_id,
+            is_stale=is_stale,
+            last_commit_time=last_commit,
+            minutes_since_commit=round(minutes_since, 1),
+            worktree_exists=True,
+        )
+
+    except Exception as e:
+        return StaleCheckResult(
+            wp_id=wp_id,
+            is_stale=False,
+            last_commit_time=None,
+            minutes_since_commit=None,
+            worktree_exists=True,
+            error=str(e),
+        )
+
+
+def find_worktree_for_wp(
+    main_repo_root: Path,
+    feature_slug: str,
+    wp_id: str,
+) -> Path | None:
+    """
+    Find the worktree path for a given work package.
+
+    Args:
+        main_repo_root: Root of the main repository
+        feature_slug: Feature slug (e.g., "001-my-feature")
+        wp_id: Work package ID (e.g., "WP01")
+
+    Returns:
+        Path to worktree if found, None otherwise
+    """
+    worktrees_dir = main_repo_root / ".worktrees"
+    if not worktrees_dir.exists():
+        return None
+
+    # Expected pattern: feature_slug-WP01
+    expected_name = f"{feature_slug}-{wp_id}"
+    worktree_path = worktrees_dir / expected_name
+
+    if worktree_path.exists():
+        return worktree_path
+
+    # Try case-insensitive search
+    for item in worktrees_dir.iterdir():
+        if item.is_dir() and item.name.lower() == expected_name.lower():
+            return item
+
+    return None
+
+
+def check_doing_wps_for_staleness(
+    main_repo_root: Path,
+    feature_slug: str,
+    doing_wps: list[dict],
+    threshold_minutes: int = 10,
+) -> dict[str, StaleCheckResult]:
+    """
+    Check all WPs in "doing" lane for staleness.
+
+    Args:
+        main_repo_root: Root of the main repository
+        feature_slug: Feature slug
+        doing_wps: List of WP dicts with at least 'id' key
+        threshold_minutes: Minutes of inactivity threshold
+
+    Returns:
+        Dict mapping WP ID to StaleCheckResult
+    """
+    results = {}
+
+    for wp in doing_wps:
+        wp_id = wp.get("id") or wp.get("work_package_id")
+        if not wp_id:
+            continue
+
+        worktree_path = find_worktree_for_wp(main_repo_root, feature_slug, wp_id)
+
+        if worktree_path:
+            result = check_wp_staleness(wp_id, worktree_path, threshold_minutes)
+        else:
+            result = StaleCheckResult(
+                wp_id=wp_id,
+                is_stale=False,
+                last_commit_time=None,
+                minutes_since_commit=None,
+                worktree_exists=False,
+            )
+
+        results[wp_id] = result
+
+    return results

specify_cli/core/tool_checker.py

@@ -0,0 +1,79 @@
+"""Tool availability helpers for Spec Kitty."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Dict, Mapping, Tuple, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from specify_cli.cli import StepTracker
+
+from specify_cli.core.config import AGENT_TOOL_REQUIREMENTS, IDE_AGENTS
+
+CLAUDE_LOCAL_PATH = Path.home() / ".claude" / "local" / "claude"
+
+
+def check_tool_for_tracker(tool: str, tracker: "StepTracker") -> bool:
+    """Check if a tool is installed and update the provided StepTracker instance."""
+    if shutil.which(tool):
+        tracker.complete(tool, "available")
+        return True
+    tracker.error(tool, "not found")
+    return False
+
+
+def check_tool(tool: str, install_hint: str, agent_name: str | None = None) -> bool:
+    """Return True when the tool is available on PATH (with Claude CLI override and IDE agent bypass).
+
+    IDE-integrated agents (cursor, windsurf, copilot, kilocode) don't require CLI
+    installation, so we skip the availability check for them.
+    """
+    # Skip CLI checks for IDE agents - they run within the IDE, not as CLI tools
+    if agent_name and agent_name in IDE_AGENTS:
+        return True
+
+    # Special case: Claude local installation
+    if tool == "claude" and CLAUDE_LOCAL_PATH.exists() and CLAUDE_LOCAL_PATH.is_file():
+        return True
+
+    return shutil.which(tool) is not None
+
+
+def get_tool_version(command: str) -> str | None:
+    """Return the version string for a tool if the convention '<tool> --version' succeeds."""
+    try:
+        result = subprocess.run(
+            [command, "--version"],
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+    except (subprocess.CalledProcessError, FileNotFoundError, OSError):
+        return None
+
+    output = (result.stdout or result.stderr or "").strip()
+    return output or None
+
+
+def check_all_tools(
+    requirements: Mapping[str, Tuple[str, str]] | None = None,
+) -> Dict[str, Tuple[bool, str]]:
+    """Check tool availability for all known agents, returning {agent: (ok, detail)}."""
+    results: Dict[str, Tuple[bool, str]] = {}
+    entries = requirements or AGENT_TOOL_REQUIREMENTS
+    for agent, (tool, url) in entries.items():
+        ok = check_tool(tool, url)
+        detail = get_tool_version(tool) if ok else url
+        results[agent] = (ok, detail or url)
+    return results
+
+
+__all__ = [
+    "check_all_tools",
+    "check_tool",
+    "check_tool_for_tracker",
+    "get_tool_version",
+]

specify_cli/core/utils.py

@@ -0,0 +1,43 @@
+"""Shared utility helpers used across Spec Kitty modules."""
+
+from __future__ import annotations
+
+import shutil
+import sys
+from pathlib import Path
+
+
+def format_path(path: Path, relative_to: Path | None = None) -> str:
+    """Return a string path, optionally relative to another directory."""
+    target = path
+    if relative_to is not None:
+        try:
+            target = path.relative_to(relative_to)
+        except ValueError:
+            target = path
+    return str(target)
+
+
+def ensure_directory(path: Path) -> Path:
+    """Create a directory (and parents) if it does not exist and return the Path."""
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def safe_remove(path: Path) -> bool:
+    """Remove a file or directory tree if it exists, returning True when something was removed."""
+    if not path.exists():
+        return False
+    if path.is_dir() and not path.is_symlink():
+        shutil.rmtree(path)
+    else:
+        path.unlink()
+    return True
+
+
+def get_platform() -> str:
+    """Return the current platform identifier (linux/darwin/win32)."""
+    return sys.platform
+
+
+__all__ = ["format_path", "ensure_directory", "safe_remove", "get_platform"]

specify_cli/core/vcs/__init__.py

@@ -0,0 +1,114 @@
+"""
+VCS Abstraction Package
+=======================
+
+This package provides a unified interface for Version Control System operations,
+supporting both Git and Jujutsu (jj) backends.
+
+Usage:
+    from specify_cli.core.vcs import (
+        get_vcs,
+        VCSProtocol,
+        VCSBackend,
+        VCSCapabilities,
+        GIT_CAPABILITIES,
+        JJ_CAPABILITIES,
+        is_jj_available,
+        is_git_available,
+    )
+
+    # Get appropriate VCS implementation
+    vcs = get_vcs(feature_path)  # Auto-detect, prefers jj
+    vcs = get_vcs(feature_path, backend=VCSBackend.GIT)  # Explicit git
+
+See kitty-specs/015-first-class-jujutsu-vcs-integration/ for full documentation.
+"""
+
+from __future__ import annotations
+
+# Enums
+from .types import (
+    ConflictType,
+    SyncStatus,
+    VCSBackend,
+)
+
+# Dataclasses
+from .types import (
+    ChangeInfo,
+    ConflictInfo,
+    FeatureVCSConfig,
+    OperationInfo,
+    ProjectVCSConfig,
+    SyncResult,
+    VCSCapabilities,
+    WorkspaceCreateResult,
+    WorkspaceInfo,
+)
+
+# Capability constants
+from .types import (
+    GIT_CAPABILITIES,
+    JJ_CAPABILITIES,
+)
+
+# Protocol
+from .protocol import VCSProtocol
+
+# Exceptions
+from .exceptions import (
+    VCSBackendMismatchError,
+    VCSCapabilityError,
+    VCSConflictError,
+    VCSError,
+    VCSLockError,
+    VCSNotFoundError,
+    VCSSyncError,
+)
+
+# Detection and factory functions
+from .detection import (
+    detect_available_backends,
+    get_git_version,
+    get_jj_version,
+    get_vcs,
+    is_git_available,
+    is_jj_available,
+)
+
+__all__ = [
+    # Enums
+    "VCSBackend",
+    "SyncStatus",
+    "ConflictType",
+    # Dataclasses
+    "VCSCapabilities",
+    "ChangeInfo",
+    "ConflictInfo",
+    "SyncResult",
+    "WorkspaceInfo",
+    "OperationInfo",
+    "WorkspaceCreateResult",
+    "ProjectVCSConfig",
+    "FeatureVCSConfig",
+    # Capability constants
+    "GIT_CAPABILITIES",
+    "JJ_CAPABILITIES",
+    # Protocol
+    "VCSProtocol",
+    # Exceptions
+    "VCSError",
+    "VCSNotFoundError",
+    "VCSCapabilityError",
+    "VCSBackendMismatchError",
+    "VCSLockError",
+    "VCSConflictError",
+    "VCSSyncError",
+    # Detection and factory
+    "get_vcs",
+    "is_jj_available",
+    "is_git_available",
+    "get_jj_version",
+    "get_git_version",
+    "detect_available_backends",
+]