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

specify_cli/orchestrator/testing/paths.py

@@ -0,0 +1,218 @@
+"""Test path selection based on agent availability.
+
+This module determines which test execution path to use based on the number
+of authenticated agents available. The path affects how tests are structured:
+
+- 1-agent: Same agent handles both implementation and review
+- 2-agent: Different agents for implementation vs review
+- 3+-agent: Third agent available for fallback scenarios
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Literal
+
+if TYPE_CHECKING:
+    pass
+
+# Module-level cache for test path
+_test_path_cache: TestPath | None = None
+
+
+@dataclass
+class TestPath:
+    """Selected test path based on runtime agent availability."""
+
+    path_type: Literal["1-agent", "2-agent", "3+-agent"]
+    """The test path variant to execute."""
+
+    available_agents: list[str]
+    """List of authenticated agent IDs available for this run."""
+
+    implementation_agent: str
+    """Agent to use for implementation phase."""
+
+    review_agent: str
+    """Agent to use for review phase."""
+
+    fallback_agent: str | None
+    """Third agent for fallback scenarios (None for 1/2-agent paths)."""
+
+    @property
+    def is_cross_agent(self) -> bool:
+        """True if implementation and review use different agents."""
+        return self.implementation_agent != self.review_agent
+
+    @property
+    def has_fallback(self) -> bool:
+        """True if a fallback agent is available."""
+        return self.fallback_agent is not None
+
+    @property
+    def agent_count(self) -> int:
+        """Number of available agents."""
+        return len(self.available_agents)
+
+
+def determine_path_type(agent_count: int) -> Literal["1-agent", "2-agent", "3+-agent"]:
+    """Determine test path type based on available agent count.
+
+    Args:
+        agent_count: Number of available (authenticated) agents
+
+    Returns:
+        Path type string indicating which test variant to run
+
+    Raises:
+        ValueError: If no agents available
+    """
+    if agent_count == 0:
+        raise ValueError("No agents available for testing")
+    elif agent_count == 1:
+        return "1-agent"
+    elif agent_count == 2:
+        return "2-agent"
+    else:
+        return "3+-agent"
+
+
+def assign_agents(
+    available_agents: list[str],
+    path_type: Literal["1-agent", "2-agent", "3+-agent"],
+) -> tuple[str, str, str | None]:
+    """Assign agents to roles based on path type.
+
+    Agents are sorted alphabetically for deterministic assignment:
+    - First agent: implementation role
+    - Second agent: review role
+    - Third agent: fallback role (if available)
+
+    Args:
+        available_agents: List of available agent IDs
+        path_type: The test path type
+
+    Returns:
+        Tuple of (implementation_agent, review_agent, fallback_agent)
+
+    Raises:
+        ValueError: If no agents available
+    """
+    if not available_agents:
+        raise ValueError("No agents available")
+
+    # Sort for deterministic assignment
+    agents = sorted(available_agents)
+
+    if path_type == "1-agent":
+        # Same agent for both roles
+        return agents[0], agents[0], None
+
+    elif path_type == "2-agent":
+        # Different agents, no fallback
+        return agents[0], agents[1], None
+
+    else:  # 3+-agent
+        # Different agents with fallback
+        return agents[0], agents[1], agents[2]
+
+
+def clear_test_path_cache() -> None:
+    """Clear the cached test path.
+
+    Call this when agent availability may have changed (e.g., during
+    test setup or teardown).
+    """
+    global _test_path_cache
+    _test_path_cache = None
+
+
+async def select_test_path(force_path: str | None = None) -> TestPath:
+    """Select test path based on available agents.
+
+    This is the main entry point for test path selection. It:
+    1. Detects available (authenticated) agents
+    2. Determines the appropriate path type
+    3. Assigns agents to roles
+    4. Caches the result for session duration
+
+    Args:
+        force_path: Optional path type to force (for testing).
+            Valid values: "1-agent", "2-agent", "3+-agent"
+
+    Returns:
+        TestPath with agent assignments
+
+    Raises:
+        ValueError: If no agents available
+    """
+    global _test_path_cache
+
+    if _test_path_cache is not None and force_path is None:
+        return _test_path_cache
+
+    # Import here to avoid circular imports and allow WP01 to be merged first
+    from specify_cli.orchestrator.testing.availability import (
+        detect_all_agents,
+        get_available_agents,
+    )
+
+    # Detect agents
+    await detect_all_agents()
+    available = get_available_agents()
+
+    if not available:
+        raise ValueError(
+            "No agents available for testing. "
+            "Install and authenticate at least one agent."
+        )
+
+    # Determine path type
+    if force_path:
+        # Validate force_path
+        if force_path not in ("1-agent", "2-agent", "3+-agent"):
+            raise ValueError(
+                f"Invalid force_path: {force_path}. "
+                "Must be '1-agent', '2-agent', or '3+-agent'"
+            )
+        path_type: Literal["1-agent", "2-agent", "3+-agent"] = force_path  # type: ignore[assignment]
+    else:
+        path_type = determine_path_type(len(available))
+
+    # Assign agents
+    impl_agent, review_agent, fallback = assign_agents(available, path_type)
+
+    test_path = TestPath(
+        path_type=path_type,
+        available_agents=available,
+        implementation_agent=impl_agent,
+        review_agent=review_agent,
+        fallback_agent=fallback,
+    )
+
+    if force_path is None:
+        _test_path_cache = test_path
+
+    return test_path
+
+
+def select_test_path_sync(force_path: str | None = None) -> TestPath:
+    """Synchronous wrapper for select_test_path.
+
+    Useful for pytest fixtures and non-async contexts.
+
+    Args:
+        force_path: Optional path type to force (for testing)
+
+    Returns:
+        TestPath with agent assignments
+    """
+    try:
+        loop = asyncio.get_running_loop()
+    except RuntimeError:
+        # No running loop - create one
+        return asyncio.run(select_test_path(force_path))
+
+    # Running loop exists - use it
+    return loop.run_until_complete(select_test_path(force_path))

specify_cli/plan_validation.py

@@ -0,0 +1,107 @@
+"""Plan validation utilities for Spec Kitty CLI.
+
+Detects whether a plan.md file has been meaningfully filled out or is still in template form.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+
+# Template markers that indicate an unfilled plan
+TEMPLATE_MARKERS = [
+    "[FEATURE]",
+    "[###-feature-name]",
+    "[DATE]",
+    "[link]",
+    "[Extract from feature spec:",
+    "ACTION REQUIRED: Replace the content",
+    "[e.g., Python 3.11",
+    "or NEEDS CLARIFICATION",
+    "# [REMOVE IF UNUSED]",
+    "[Gates determined based on constitution file]",
+    "[Document the selected structure",
+]
+
+# Minimum number of template markers that must be removed for plan to be considered filled
+MIN_MARKERS_TO_REMOVE = 5
+
+
+class PlanValidationError(Exception):
+    """Raised when plan.md validation fails."""
+
+    pass
+
+
+def detect_unfilled_plan(plan_path: Path) -> tuple[bool, list[str]]:
+    """Check if plan.md is still in template form.
+
+    Args:
+        plan_path: Path to the plan.md file
+
+    Returns:
+        Tuple of (is_unfilled, list of markers found)
+        - is_unfilled: True if the plan appears to be unfilled template
+        - markers: List of template markers still present in the file
+    """
+    if not plan_path.exists():
+        return False, []
+
+    try:
+        content = plan_path.read_text(encoding="utf-8-sig")
+    except Exception:
+        # If we can't read it, assume it's filled (don't block progress)
+        return False, []
+
+    found_markers = []
+    for marker in TEMPLATE_MARKERS:
+        if marker in content:
+            found_markers.append(marker)
+
+    # Consider unfilled if multiple key markers are still present
+    is_unfilled = len(found_markers) >= MIN_MARKERS_TO_REMOVE
+
+    return is_unfilled, found_markers
+
+
+def validate_plan_filled(
+    plan_path: Path,
+    *,
+    feature_slug: Optional[str] = None,
+    strict: bool = True,
+) -> None:
+    """Validate that plan.md has been filled out.
+
+    Args:
+        plan_path: Path to the plan.md file
+        feature_slug: Optional feature slug for error messages
+        strict: If True, raise error on unfilled plan. If False, just warn.
+
+    Raises:
+        PlanValidationError: If plan is unfilled and strict=True
+    """
+    is_unfilled, markers = detect_unfilled_plan(plan_path)
+
+    if not is_unfilled:
+        return
+
+    feature_display = f" for feature '{feature_slug}'" if feature_slug else ""
+    marker_list = "\n  - ".join(markers[:5])  # Show first 5 markers
+    more_markers = f"\n  ... and {len(markers) - 5} more" if len(markers) > 5 else ""
+
+    error_msg = (
+        f"plan.md{feature_display} appears to be unfilled (template form).\n"
+        f"Found {len(markers)} template markers:\n  - {marker_list}{more_markers}\n\n"
+        f"Please complete the /spec-kitty.plan workflow before proceeding to research or tasks.\n"
+        f"The plan.md file must have technical details filled in, not just template placeholders."
+    )
+
+    if strict:
+        raise PlanValidationError(error_msg)
+    else:
+        import sys
+        print(f"Warning: {error_msg}", file=sys.stderr)
+
+
+__all__ = ["PlanValidationError", "detect_unfilled_plan", "validate_plan_filled"]

specify_cli/scripts/debug-dashboard-scan.py

@@ -0,0 +1,61 @@
+#!/usr/bin/env python3
+"""Debug script to test dashboard feature scanning."""
+
+import sys
+from pathlib import Path
+
+# Add src to path
+sys.path.insert(0, str(Path(__file__).parent.parent / "src"))
+
+from specify_cli.dashboard.scanner import scan_all_features, gather_feature_paths
+
+def main():
+    if len(sys.argv) > 1:
+        project_dir = Path(sys.argv[1]).resolve()
+    else:
+        project_dir = Path.cwd()
+
+    print(f"Scanning project directory: {project_dir}")
+    print()
+
+    # Test gather_feature_paths
+    print("=== Feature Paths ===")
+    feature_paths = gather_feature_paths(project_dir)
+    if not feature_paths:
+        print("  No features found!")
+        print()
+        print("Checking directories:")
+        print(f"  Main specs: {project_dir / 'kitty-specs'} exists: {(project_dir / 'kitty-specs').exists()}")
+        print(f"  Worktrees: {project_dir / '.worktrees'} exists: {(project_dir / '.worktrees').exists()}")
+
+        if (project_dir / '.worktrees').exists():
+            for wt_dir in (project_dir / '.worktrees').iterdir():
+                if wt_dir.is_dir():
+                    wt_specs = wt_dir / 'kitty-specs'
+                    print(f"    {wt_dir.name}/kitty-specs exists: {wt_specs.exists()}")
+                    if wt_specs.exists():
+                        for feat_dir in wt_specs.iterdir():
+                            if feat_dir.is_dir():
+                                print(f"      Feature: {feat_dir.name}")
+    else:
+        for feature_id, feature_path in feature_paths.items():
+            print(f"  {feature_id}: {feature_path}")
+    print()
+
+    # Test scan_all_features
+    print("=== Scanned Features ===")
+    features = scan_all_features(project_dir)
+    if not features:
+        print("  No features scanned!")
+    else:
+        for feature in features:
+            print(f"  ID: {feature['id']}")
+            print(f"    Name: {feature['name']}")
+            print(f"    Path: {feature['path']}")
+            print(f"    Artifacts: {feature['artifacts']}")
+            print(f"    Workflow: {feature['workflow']}")
+            print(f"    Kanban: {feature['kanban_stats']}")
+            print()
+
+if __name__ == "__main__":
+    main()