specfact-cli 0.4.0__py3-none-any.whl

specfact_cli/agents/plan_agent.py

@@ -0,0 +1,202 @@
+"""
+Plan Agent - Plan management with business logic understanding.
+
+This module provides the PlanAgent for plan management operations with
+enhanced prompts and context injection for CoPilot integration.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from beartype import beartype
+from icontract import ensure, require
+
+from specfact_cli.agents.base import AgentMode
+
+
+class PlanAgent(AgentMode):
+    """
+    Plan management agent with business logic understanding.
+
+    Provides enhanced prompts for plan management operations with
+    context injection from IDE and repository analysis.
+    """
+
+    @beartype
+    @require(lambda command: bool(command), "Command must be non-empty")
+    @ensure(lambda result: isinstance(result, str) and bool(result), "Prompt must be non-empty string")
+    def generate_prompt(self, command: str, context: dict[str, Any] | None = None) -> str:
+        """
+        Generate enhanced prompt for plan management.
+
+        Args:
+            command: CLI command being executed (e.g., "plan init", "plan compare")
+            context: Context dictionary with current file, selection, workspace
+
+        Returns:
+            Enhanced prompt optimized for CoPilot
+
+        Examples:
+            >>> agent = PlanAgent()
+            >>> prompt = agent.generate_prompt("plan init", {"current_file": "idea.yaml"})
+            >>> "interactive" in prompt.lower()
+            True
+        """
+        if context is None:
+            context = {}
+
+        current_file = context.get("current_file", "")
+        selection = context.get("selection", "")
+        workspace = context.get("workspace", "")
+
+        if command in ("plan promote", "plan adopt"):
+            auto_plan_path = context.get("auto_plan_path", "")
+            auto_plan_content = ""
+            if auto_plan_path and Path(auto_plan_path).exists():
+                auto_plan_content = Path(auto_plan_path).read_text()[:500]  # Limit length
+
+            prompt = f"""
+Analyze the repository and cross-validate identified features/stories.
+
+Repository Context:
+- Workspace: {workspace or "None"}
+- Current file: {current_file or "None"}
+- Selection: {selection or "None"}
+
+Auto-Derived Plan (from AST analysis):
+{auto_plan_content[:500] if auto_plan_content else "None"}
+
+Tasks:
+1. Validate each identified feature exists in the codebase
+2. Identify missing features that AST analysis missed
+3. Identify false positives (classes/components that aren't features)
+4. Cross-validate stories against actual code
+5. Refine confidence scores based on code quality and documentation
+6. Suggest theme categorization improvements
+7. Extract business context from code comments/docs
+
+Output Format:
+- Validated features list with refined confidence scores
+- Missing features (AI discovered, not in AST analysis)
+- False positives (features to remove from plan)
+- Story mapping validation (corrections needed)
+- Theme categorization suggestions
+- Business context extraction (idea, target users, value hypothesis)
+"""
+        elif command == "plan init":
+            prompt = f"""
+Initialize plan bundle with interactive wizard.
+
+Context:
+- Current file: {current_file or "None"}
+- Selection: {selection or "None"}
+- Workspace: {workspace or "None"}
+
+Extract from context:
+1. Idea from selection or current file
+2. Business plan structure
+3. Product plan themes
+4. Features from workspace structure
+
+Generate interactive prompts for missing information.
+"""
+        elif command == "plan compare":
+            prompt = f"""
+Compare manual vs auto-derived plans.
+
+Context:
+- Current file: {current_file or "None"}
+- Selection: {selection or "None"}
+- Workspace: {workspace or "None"}
+
+Focus on:
+1. Deviation explanations
+2. Fix suggestions
+3. Interactive deviation review
+
+Generate rich console output with explanations.
+"""
+        else:
+            prompt = f"Execute plan command: {command}"
+
+        return prompt.strip()
+
+    @beartype
+    @require(lambda command: bool(command), "Command must be non-empty")
+    @ensure(lambda result: isinstance(result, dict), "Result must be a dictionary")
+    def execute(
+        self, command: str, args: dict[str, Any] | None = None, context: dict[str, Any] | None = None
+    ) -> dict[str, Any]:
+        """
+        Execute plan command with enhanced prompts.
+
+        Args:
+            command: CLI command being executed (e.g., "plan init")
+            args: Command arguments (e.g., {"idea": "idea.yaml"})
+            context: Context dictionary with current file, selection, workspace
+
+        Returns:
+            Command result with enhanced output
+
+        Examples:
+            >>> agent = PlanAgent()
+            >>> result = agent.execute("plan init", {"idea": "idea.yaml"}, {"current_file": "idea.yaml"})
+            >>> isinstance(result, dict)
+            True
+        """
+        if args is None:
+            args = {}
+        if context is None:
+            context = {}
+
+        # Generate enhanced prompt
+        prompt = self.generate_prompt(command, context)
+
+        # For Phase 4.1, return structured result with prompt
+        # In Phase 4.2+, this will route to actual command execution with agent mode
+        return {
+            "type": "plan",
+            "command": command,
+            "prompt": prompt,
+            "args": args,
+            "context": context,
+            "enhanced": True,
+        }
+
+    @beartype
+    @ensure(lambda result: isinstance(result, dict), "Result must be a dictionary")
+    def inject_context(self, context: dict[str, Any] | None = None) -> dict[str, Any]:
+        """
+        Inject context information specific to plan operations.
+
+        Args:
+            context: Basic context dictionary (can be None)
+
+        Returns:
+            Enhanced context with plan-specific information
+
+        Examples:
+            >>> agent = PlanAgent()
+            >>> enhanced = agent.inject_context({"current_file": "idea.yaml"})
+            >>> isinstance(enhanced, dict)
+            True
+        """
+        enhanced = super().inject_context(context)
+
+        # Add plan artifacts if workspace is available
+        if enhanced.get("workspace"):
+            workspace_path = Path(enhanced["workspace"])
+            if workspace_path.exists() and workspace_path.is_dir():
+                # Find plan artifacts
+                plan_artifacts = {}
+                specfact_dir = workspace_path / ".specfact"
+                if specfact_dir.exists():
+                    plans_dir = specfact_dir / "plans"
+                    if plans_dir.exists():
+                        plan_files = list(plans_dir.glob("*.yaml")) + list(plans_dir.glob("*.yml"))
+                        plan_artifacts["plan_files"] = [str(f) for f in plan_files[:5]]  # Limit to first 5
+                enhanced["plan_artifacts"] = plan_artifacts
+
+        return enhanced

specfact_cli/agents/registry.py

@@ -0,0 +1,176 @@
+"""
+Agent Registry - Registry for agent mode instances.
+
+This module provides a registry for managing agent mode instances and
+routing commands to appropriate agents based on command type.
+"""
+
+from __future__ import annotations
+
+from beartype import beartype
+from icontract import ensure, require
+
+from specfact_cli.agents.analyze_agent import AnalyzeAgent
+from specfact_cli.agents.base import AgentMode
+from specfact_cli.agents.plan_agent import PlanAgent
+from specfact_cli.agents.sync_agent import SyncAgent
+
+
+class AgentRegistry:
+    """
+    Registry for agent mode instances.
+
+    Provides centralized management of agent instances and routing
+    based on command type.
+    """
+
+    def __init__(self) -> None:
+        """Initialize agent registry with default agents."""
+        self._agents: dict[str, AgentMode] = {}
+        self._register_default_agents()
+
+    @beartype
+    def _register_default_agents(self) -> None:
+        """Register default agent instances."""
+        self._agents["analyze"] = AnalyzeAgent()
+        self._agents["plan"] = PlanAgent()
+        self._agents["sync"] = SyncAgent()
+
+    @beartype
+    @require(lambda name: bool(name), "Agent name must be non-empty")
+    @require(lambda agent: isinstance(agent, AgentMode), "Agent must be AgentMode instance")
+    def register(self, name: str, agent: AgentMode) -> None:
+        """
+        Register an agent instance.
+
+        Args:
+            name: Agent name (e.g., "analyze", "plan", "sync")
+            agent: Agent mode instance
+
+        Examples:
+            >>> registry = AgentRegistry()
+            >>> registry.register("custom", AnalyzeAgent())
+        """
+        self._agents[name] = agent
+
+    @beartype
+    @require(lambda name: bool(name), "Agent name must be non-empty")
+    @ensure(lambda result: result is None or isinstance(result, AgentMode), "Result must be AgentMode or None")
+    def get(self, name: str) -> AgentMode | None:
+        """
+        Get an agent instance by name.
+
+        Args:
+            name: Agent name (e.g., "analyze", "plan", "sync")
+
+        Returns:
+            Agent mode instance or None if not found
+
+        Examples:
+            >>> registry = AgentRegistry()
+            >>> agent = registry.get("analyze")
+            >>> isinstance(agent, AnalyzeAgent)
+            True
+        """
+        return self._agents.get(name)
+
+    @beartype
+    @require(lambda command: bool(command), "Command must be non-empty")
+    @ensure(lambda result: result is None or isinstance(result, AgentMode), "Result must be AgentMode or None")
+    def get_agent_for_command(self, command: str) -> AgentMode | None:
+        """
+        Get agent instance for a command.
+
+        Args:
+            command: CLI command (e.g., "import from-code", "plan init", "sync spec-kit")
+
+        Returns:
+            Agent mode instance or None if not found
+
+        Examples:
+            >>> registry = AgentRegistry()
+            >>> agent = registry.get_agent_for_command("import from-code")
+            >>> isinstance(agent, AnalyzeAgent)
+            True
+        """
+        # Extract command type from command string
+        command_parts = command.split()
+        if not command_parts:
+            return None
+
+        command_type = command_parts[0]
+
+        # Map command types to agent names
+        agent_map: dict[str, str] = {
+            "import": "analyze",  # import from-code uses AnalyzeAgent
+            "plan": "plan",
+            "sync": "sync",
+        }
+
+        agent_name = agent_map.get(command_type)
+        if agent_name:
+            return self.get(agent_name)
+
+        return None
+
+    @beartype
+    def list_agents(self) -> list[str]:
+        """
+        List all registered agent names.
+
+        Returns:
+            List of agent names
+
+        Examples:
+            >>> registry = AgentRegistry()
+            >>> names = registry.list_agents()
+            >>> "analyze" in names
+            True
+        """
+        return list(self._agents.keys())
+
+
+# Global registry instance
+_registry: AgentRegistry | None = None
+
+
+@beartype
+@ensure(lambda result: isinstance(result, AgentRegistry), "Result must be AgentRegistry")
+def get_registry() -> AgentRegistry:
+    """
+    Get the global agent registry instance.
+
+    Returns:
+        AgentRegistry instance
+
+    Examples:
+        >>> registry = get_registry()
+        >>> isinstance(registry, AgentRegistry)
+        True
+    """
+    global _registry
+    if _registry is None:
+        _registry = AgentRegistry()
+    return _registry
+
+
+@beartype
+@require(lambda command: bool(command), "Command must be non-empty")
+@ensure(lambda result: result is None or isinstance(result, AgentMode), "Result must be AgentMode or None")
+def get_agent(command: str) -> AgentMode | None:
+    """
+    Get agent instance for a command (convenience function).
+
+    Args:
+        command: CLI command (e.g., "import from-code")
+
+    Returns:
+        Agent mode instance or None if not found
+
+    Examples:
+        >>> agent = get_agent("import from-code")
+        >>> isinstance(agent, AnalyzeAgent)
+        True
+    """
+    registry = get_registry()
+    return registry.get_agent_for_command(command)

specfact_cli/agents/sync_agent.py

@@ -0,0 +1,133 @@
+"""
+Sync Agent - Bidirectional sync with conflict resolution.
+
+This module provides the SyncAgent for sync operations with enhanced
+prompts and conflict resolution assistance for CoPilot integration.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from beartype import beartype
+from icontract import ensure, require
+
+from specfact_cli.agents.base import AgentMode
+
+
+class SyncAgent(AgentMode):
+    """
+    Bidirectional sync agent with conflict resolution.
+
+    Provides enhanced prompts for sync operations with conflict
+    resolution assistance and change explanation.
+    """
+
+    @beartype
+    @require(lambda command: bool(command), "Command must be non-empty")
+    @ensure(lambda result: isinstance(result, str) and bool(result), "Prompt must be non-empty string")
+    def generate_prompt(self, command: str, context: dict[str, Any] | None = None) -> str:
+        """
+        Generate enhanced prompt for sync operation.
+
+        Args:
+            command: CLI command being executed (e.g., "sync spec-kit", "sync repository")
+            context: Context dictionary with current file, selection, workspace
+
+        Returns:
+            Enhanced prompt optimized for CoPilot
+
+        Examples:
+            >>> agent = SyncAgent()
+            >>> prompt = agent.generate_prompt("sync spec-kit", {"workspace": "."})
+            >>> "conflict" in prompt.lower()
+            True
+        """
+        if context is None:
+            context = {}
+
+        current_file = context.get("current_file", "")
+        selection = context.get("selection", "")
+        workspace = context.get("workspace", "")
+
+        prompt = f"""
+Perform bidirectional sync with conflict resolution.
+
+Context:
+- Current file: {current_file or "None"}
+- Selection: {selection or "None"}
+- Workspace: {workspace or "None"}
+
+Sync strategy:
+1. Detect changes in Spec-Kit artifacts and .specfact/ artifacts
+2. Automatic source detection
+3. Conflict resolution assistance
+4. Change explanation and preview
+
+Generate interactive conflict resolution prompts.
+"""
+        return prompt.strip()
+
+    @beartype
+    @require(lambda command: bool(command), "Command must be non-empty")
+    @ensure(lambda result: isinstance(result, dict), "Result must be a dictionary")
+    def execute(
+        self, command: str, args: dict[str, Any] | None = None, context: dict[str, Any] | None = None
+    ) -> dict[str, Any]:
+        """
+        Execute sync command with enhanced prompts.
+
+        Args:
+            command: CLI command being executed (e.g., "sync spec-kit")
+            args: Command arguments (e.g., {"source": "spec-kit", "target": ".specfact"})
+            context: Context dictionary with current file, selection, workspace
+
+        Returns:
+            Command result with enhanced output
+
+        Examples:
+            >>> agent = SyncAgent()
+            >>> result = agent.execute("sync spec-kit", {"source": "spec-kit"}, {"workspace": "."})
+            >>> isinstance(result, dict)
+            True
+        """
+        if args is None:
+            args = {}
+        if context is None:
+            context = {}
+
+        # Generate enhanced prompt
+        prompt = self.generate_prompt(command, context)
+
+        # For Phase 4.1, return structured result with prompt
+        # In Phase 4.2+, this will route to actual command execution with agent mode
+        return {
+            "type": "sync",
+            "command": command,
+            "prompt": prompt,
+            "args": args,
+            "context": context,
+            "enhanced": True,
+        }
+
+    @beartype
+    @ensure(lambda result: isinstance(result, dict), "Result must be a dictionary")
+    def inject_context(self, context: dict[str, Any] | None = None) -> dict[str, Any]:
+        """
+        Inject context information specific to sync operations.
+
+        Args:
+            context: Basic context dictionary (can be None)
+
+        Returns:
+            Enhanced context with sync-specific information
+
+        Examples:
+            >>> agent = SyncAgent()
+            >>> enhanced = agent.inject_context({"workspace": "."})
+            >>> isinstance(enhanced, dict)
+            True
+        """
+        # Sync-specific context injection will be enhanced in Phase 4.2+
+        # For now, just return the enhanced context from base class
+        return super().inject_context(context)

specfact_cli/analyzers/__init__.py

@@ -0,0 +1,10 @@
+"""
+Analyzers module for SpecFact CLI.
+
+This module provides classes for analyzing code to extract features,
+stories, and generate plan bundles from brownfield codebases.
+"""
+
+from specfact_cli.analyzers.code_analyzer import CodeAnalyzer
+
+__all__ = ["CodeAnalyzer"]