titan-cli 0.1.0__py3-none-any.whl

titan_cli/core/workflows/workflow_sources.py

@@ -0,0 +1,307 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import List, Optional, Set, Protocol
+import yaml
+from dataclasses import dataclass, field
+
+
+class PluginRegistryProtocol(Protocol):
+    """Protocol defining the interface that PluginRegistry must implement for workflow sources."""
+
+    def list_installed(self) -> List[str]:
+        """List successfully loaded plugins."""
+        ...
+
+    def get_plugin(self, name: str):
+        """Get plugin instance by name."""
+        ...
+
+@dataclass
+class WorkflowInfo:
+    """Metadata about a discovered, but not yet parsed, workflow."""
+    name: str
+    description: str
+    source: str  # "project", "user", "system", "plugin:github"
+    path: Path
+    category: Optional[str] = None
+    required_plugins: Set[str] = field(default_factory=set)
+
+def _parse_workflow_info(file: Path, source_name: str, plugin_registry: PluginRegistryProtocol) -> WorkflowInfo:
+    """
+    Helper to extract metadata and plugin dependencies from a workflow file.
+    Does not resolve 'extends' or nested 'workflow' calls to keep discovery fast.
+    """
+    try:
+        with open(file, 'r', encoding='utf-8') as f:
+            config = yaml.safe_load(f) or {}
+    except Exception:
+        config = {}
+
+    required_plugins: Set[str] = set()
+    
+    # Check direct plugin dependencies in steps
+    steps = config.get("steps", [])
+    if isinstance(steps, list):
+        for step in steps:
+            if isinstance(step, dict) and "plugin" in step and step["plugin"] not in ["core", "project"]:
+                required_plugins.add(step["plugin"])
+
+    # Check 'extends' field for plugin dependencies
+    extends_ref = config.get("extends")
+    if extends_ref and isinstance(extends_ref, str):
+        if extends_ref.startswith("plugin:"):
+            # Extract plugin name from "plugin:git/commit-ai" -> "git"
+            plugin_part = extends_ref.split(':', 1)[1]
+            plugin_name = plugin_part.split('/', 1)[0]
+            required_plugins.add(plugin_name)
+
+    return WorkflowInfo(
+        name=file.stem,
+        description=config.get("description", "No description available."),
+        source=source_name,
+        path=file,
+        category=config.get("category"),
+        required_plugins=required_plugins
+    )
+
+
+class WorkflowSource(ABC):
+    """
+    Abstract base class for a source of workflows.
+    This pattern allows discovering workflows from the project, user's home,
+    system-wide, or from plugins, in a uniform way.
+    """
+    def __init__(self, plugin_registry: PluginRegistryProtocol):
+        self._plugin_registry = plugin_registry
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """The unique name of the source (e.g., 'project', 'user', 'plugin:github')."""
+        pass
+
+    @abstractmethod
+    def discover(self) -> List[WorkflowInfo]:
+        """Discover all available workflows from this source."""
+        pass
+
+    @abstractmethod
+    def find(self, name: str) -> Optional[Path]:
+        """Find a specific workflow file by its name within this source."""
+        pass
+
+    @abstractmethod
+    def contains(self, path: Path) -> bool:
+        """Check if a given file path belongs to this source."""
+        pass
+
+class ProjectWorkflowSource(WorkflowSource):
+    """
+    Represents workflows defined within the current project
+    at the conventional '.titan/workflows/' directory.
+    """
+
+    def __init__(self, path: Path, plugin_registry: PluginRegistryProtocol):
+        super().__init__(plugin_registry)
+        self._path = path.resolve()
+
+    @property
+    def name(self) -> str:
+        return "project"
+
+    def discover(self) -> List[WorkflowInfo]:
+        """Discovers all .yaml or .yml files in the project's workflow directory."""
+        if not self._path.is_dir():
+            return []
+
+        workflows = []
+        for file in self._path.glob("*.yaml"):
+            workflows.append(self._to_workflow_info(file))
+        for file in self._path.glob("*.yml"):
+            if file.stem not in [w.name for w in workflows]: # Avoid duplicates if both .yaml and .yml exist
+                workflows.append(self._to_workflow_info(file))
+        return workflows
+
+    def find(self, name: str) -> Optional[Path]:
+        """Finds a workflow by name in the project directory."""
+        yaml_file = self._path / f"{name}.yaml"
+        if yaml_file.is_file():
+            return yaml_file
+        
+        yml_file = self._path / f"{name}.yml"
+        if yml_file.is_file():
+            return yml_file
+            
+        return None
+
+    def contains(self, path: Path) -> bool:
+        """Checks if the given path is within this project's workflow directory."""
+        try:
+            path.resolve().relative_to(self._path)
+            return True
+        except ValueError:
+            return False
+
+    def _to_workflow_info(self, file: Path) -> WorkflowInfo:
+        """Helper to extract metadata from a workflow file."""
+        return _parse_workflow_info(file, self.name, self._plugin_registry)
+
+class UserWorkflowSource(WorkflowSource):
+    """
+    Represents workflows defined by the user in their home directory
+    at '~/.titan/workflows/'.
+    """
+
+    def __init__(self, path: Path, plugin_registry: PluginRegistryProtocol):
+        super().__init__(plugin_registry)
+        self._path = path.expanduser().resolve()
+
+    @property
+    def name(self) -> str:
+        return "user"
+
+    def discover(self) -> List[WorkflowInfo]:
+        if not self._path.is_dir():
+            return []
+        
+        workflows = []
+        for file in self._path.glob("*.yaml"):
+            workflows.append(self._to_workflow_info(file))
+        for file in self._path.glob("*.yml"):
+            if file.stem not in [w.name for w in workflows]:
+                workflows.append(self._to_workflow_info(file))
+        return workflows
+
+    def find(self, name: str) -> Optional[Path]:
+        yaml_file = self._path / f"{name}.yaml"
+        if yaml_file.is_file():
+            return yaml_file
+        yml_file = self._path / f"{name}.yml"
+        if yml_file.is_file():
+            return yml_file
+        return None
+
+    def contains(self, path: Path) -> bool:
+        try:
+            path.resolve().relative_to(self._path)
+            return True
+        except ValueError:
+            return False
+
+    def _to_workflow_info(self, file: Path) -> WorkflowInfo:
+        return _parse_workflow_info(file, self.name, self._plugin_registry)
+
+class SystemWorkflowSource(WorkflowSource):
+    """
+    Represents workflows bundled with the Titan CLI itself,
+    typically found in a 'workflows' directory within the installed package.
+    """
+
+    def __init__(self, path: Path, plugin_registry: PluginRegistryProtocol):
+        super().__init__(plugin_registry)
+        self._path = path.resolve()
+
+    @property
+    def name(self) -> str:
+        return "system"
+
+    def discover(self) -> List[WorkflowInfo]:
+        if not self._path.is_dir():
+            return []
+        
+        workflows = []
+        for file in self._path.glob("*.yaml"):
+            workflows.append(self._to_workflow_info(file))
+        for file in self._path.glob("*.yml"):
+            if file.stem not in [w.name for w in workflows]:
+                workflows.append(self._to_workflow_info(file))
+        return workflows
+
+    def find(self, name: str) -> Optional[Path]:
+        yaml_file = self._path / f"{name}.yaml"
+        if yaml_file.is_file():
+            return yaml_file
+        yml_file = self._path / f"{name}.yml"
+        if yml_file.is_file():
+            return yml_file
+        return None
+
+    def contains(self, path: Path) -> bool:
+        try:
+            path.resolve().relative_to(self._path)
+            return True
+        except ValueError:
+            return False
+
+    def _to_workflow_info(self, file: Path) -> WorkflowInfo:
+        return _parse_workflow_info(file, self.name, self._plugin_registry)
+
+class PluginWorkflowSource(WorkflowSource):
+    """
+    Represents workflows provided by installed Titan plugins.
+    Discovers workflows via the `workflows_path` property of `TitanPlugin` instances.
+    """
+
+    def __init__(self, plugin_registry: PluginRegistryProtocol): # Remove registry here
+        super().__init__(plugin_registry)
+        self._plugin_registry = plugin_registry
+
+    @property
+    def name(self) -> str:
+        return "plugin"
+
+    def discover(self) -> List[WorkflowInfo]:
+        workflows = []
+        for plugin_name in self._plugin_registry.list_installed():
+            plugin_instance = self._plugin_registry.get_plugin(plugin_name)
+            if plugin_instance and plugin_instance.workflows_path:
+                plugin_workflows_dir = plugin_instance.workflows_path
+                if plugin_workflows_dir.is_dir():
+                    for file in plugin_workflows_dir.glob("*.yaml"):
+                        workflows.append(self._to_workflow_info(file, plugin_name))
+                    for file in plugin_workflows_dir.glob("*.yml"):
+                        if file.stem not in [w.name for w in workflows]:
+                            workflows.append(self._to_workflow_info(file, plugin_name))
+        return workflows
+
+    def find(self, name: str) -> Optional[Path]:
+        # Handle qualified names like "github/create-pr"
+        if "/" in name:
+            plugin_name_ref, workflow_name = name.split('/', 1)
+            plugin_instance = self._plugin_registry.get_plugin(plugin_name_ref)
+            if plugin_instance and plugin_instance.workflows_path:
+                plugin_workflows_dir = plugin_instance.workflows_path
+                yaml_file = plugin_workflows_dir / f"{workflow_name}.yaml"
+                if yaml_file.is_file():
+                    return yaml_file
+                yml_file = plugin_workflows_dir / f"{workflow_name}.yml"
+                if yml_file.is_file():
+                    return yml_file
+            return None # If qualified name is used, only search that plugin
+
+        # Fallback to original behavior for unqualified names
+        for plugin_name in self._plugin_registry.list_installed():
+            plugin_instance = self._plugin_registry.get_plugin(plugin_name)
+            if plugin_instance and plugin_instance.workflows_path:
+                plugin_workflows_dir = plugin_instance.workflows_path
+                yaml_file = plugin_workflows_dir / f"{name}.yaml"
+                if yaml_file.is_file():
+                    return yaml_file
+                yml_file = plugin_workflows_dir / f"{name}.yml"
+                if yml_file.is_file():
+                    return yml_file
+        return None
+
+    def contains(self, path: Path) -> bool:
+        # This is complex to determine definitively without iterating all plugins.
+        # For simplicity, we can assume if a path contains 'plugins' in its parts, it might be a plugin workflow.
+        # A more robust check would involve checking against all known plugin_instance.workflows_path.
+        return "plugins" in path.parts # Heuristic, might need refinement
+
+    def _to_workflow_info(self, file: Path, plugin_name: str) -> WorkflowInfo:
+        info = _parse_workflow_info(file, f"plugin:{plugin_name}", self._plugin_registry) # Pass plugin_registry
+        # For plugin workflows, the name is qualified, e.g., "github/create-pr"
+        # but the file.stem is just "create-pr". We'll handle this in the registry.
+        return info

titan_cli/engine/__init__.py

@@ -0,0 +1,39 @@
+"""
+Titan CLI Workflow Engine
+
+This module provides the execution engine for composing and running workflows
+using the Atomic Steps Pattern.
+
+Core components:
+- WorkflowResult types (Success, Error, Skip)
+- WorkflowContext for dependency injection
+- WorkflowContextBuilder for fluent API
+- WorkflowExecutor for executing YAML workflows (see workflow_executor.py)
+"""
+
+from .results import (
+    WorkflowResult,
+    Success,
+    Error,
+    Skip,
+    is_success,
+    is_error,
+    is_skip,
+)
+from .context import WorkflowContext
+from .builder import WorkflowContextBuilder
+
+__all__ = [
+    # Result types
+    "WorkflowResult",
+    "Success",
+    "Error",
+    "Skip",
+    # Helper functions
+    "is_success",
+    "is_error",
+    "is_skip",
+    # Context & builder
+    "WorkflowContext",
+    "WorkflowContextBuilder",
+]

titan_cli/engine/builder.py

@@ -0,0 +1,159 @@
+"""
+WorkflowContextBuilder - Fluent API for building WorkflowContext.
+"""
+from __future__ import annotations
+
+from typing import Optional, Any
+
+from titan_cli.core.plugins.plugin_registry import PluginRegistry
+from titan_cli.core.models import AIConfig
+from titan_cli.core.secrets import SecretManager
+from .context import WorkflowContext
+from titan_cli.ai.client import AIClient
+from titan_cli.ai.exceptions import AIConfigurationError
+
+
+class WorkflowContextBuilder:
+    """
+    Fluent builder for WorkflowContext.
+
+    Example:
+        plugin_registry = PluginRegistry()
+        secrets = SecretManager()
+        ai_config = AIConfig(provider="anthropic", model="claude-3-haiku-20240307")
+        ctx = WorkflowContextBuilder(plugin_registry, secrets, ai_config) \\
+            .with_ai() \\
+            .build()
+    """
+
+    def __init__(
+        self,
+        plugin_registry: PluginRegistry,
+        secrets: SecretManager,
+        ai_config: Optional[AIConfig] = None
+    ):
+        """
+        Initialize builder.
+
+        Args:
+            plugin_registry: The PluginRegistry instance.
+            secrets: The SecretManager instance.
+            ai_config: Optional AI configuration.
+        """
+        self._plugin_registry = plugin_registry
+        self._secrets = secrets
+        self._ai_config = ai_config
+
+        # Service clients
+        self._ai = None
+        self._git = None
+        self._github = None
+        self._jira = None
+
+    def with_ai(self, ai_client: Optional[Any] = None) -> WorkflowContextBuilder:
+        """
+        Add AI client.
+
+        Args:
+            ai_client: Optional AIClient instance (auto-created if None)
+        """
+        if ai_client:
+            # DI pure
+            self._ai = ai_client
+        else:
+            # Convenience - auto-create from ai_config
+            if self._ai_config:
+                try:
+                    self._ai = AIClient(self._ai_config, self._secrets)
+                except AIConfigurationError:
+                    self._ai = None
+            else:
+                self._ai = None
+        return self
+
+    def with_git(self, git_client: Optional[Any] = None) -> "WorkflowContextBuilder":
+        """
+        Add Git client.
+
+        Args:
+            git_client: Optional GitClient instance (auto-created if None)
+        """
+        if git_client:
+            self._git = git_client
+        else:
+            # Auto-create from plugin registry
+            git_plugin = self._plugin_registry.get_plugin("git")
+            if git_plugin and git_plugin.is_available():
+                try:
+                    self._git = git_plugin.get_client()
+                except Exception: # Catch any exception during client retrieval
+                    self._git = None # Fail silently
+            else:
+                self._git = None
+        return self
+
+    def with_github(self, github_client: Optional[Any] = None) -> "WorkflowContextBuilder":
+        """
+        Add GitHub client.
+
+        Args:
+            github_client: Optional GitHubClient instance (auto-loaded if None)
+        """
+        if github_client:
+            self._github = github_client
+        else:
+            # Auto-create from plugin registry
+            github_plugin = self._plugin_registry.get_plugin("github")
+            if github_plugin and github_plugin.is_available():
+                try:
+                    self._github = github_plugin.get_client()
+                except Exception: # Catch any exception during client retrieval
+                    self._github = None # Fail silently
+            else:
+                self._github = None
+        return self
+
+    def with_jira(self, jira_client: Optional[Any] = None) -> "WorkflowContextBuilder":
+        """
+        Add JIRA client to workflow context.
+
+        The JIRA client is optional and only used by JIRA plugin steps.
+        Other plugin steps will have ctx.jira = None and should ignore it.
+
+        Args:
+            jira_client: Optional JiraClient instance (auto-loaded if None).
+                        If None, attempts to load from JIRA plugin registry.
+                        If plugin is not available or fails to load, sets ctx.jira = None.
+
+        Returns:
+            Self for method chaining
+
+        Note:
+            Steps from other plugins do not need to handle ctx.jira.
+            Only JIRA plugin steps should check for and use ctx.jira.
+        """
+        if jira_client:
+            self._jira = jira_client
+        else:
+            # Auto-create from plugin registry
+            jira_plugin = self._plugin_registry.get_plugin("jira")
+            if jira_plugin and jira_plugin.is_available():
+                try:
+                    self._jira = jira_plugin.get_client()
+                except Exception: # Catch any exception during client retrieval
+                    self._jira = None # Fail silently
+            else:
+                self._jira = None
+        return self
+
+
+    def build(self) -> WorkflowContext:
+        """Build the WorkflowContext."""
+        return WorkflowContext(
+            secrets=self._secrets,
+            plugin_manager=self._plugin_registry,
+            ai=self._ai,
+            git=self._git,
+            github=self._github,
+            jira=self._jira,
+        )

titan_cli/engine/context.py

@@ -0,0 +1,82 @@
+"""
+WorkflowContext - Dependency injection container for workflows.
+"""
+
+from typing import Optional, Dict, Any, List
+from dataclasses import dataclass, field
+
+from titan_cli.core.secrets import SecretManager
+
+
+@dataclass
+class WorkflowContext:
+    """
+    Context container for workflow execution.
+
+    Provides:
+    - Dependency injection (clients, services)
+    - Shared data storage between steps
+    - Textual TUI components
+    - Access to secrets
+
+    UI Architecture:
+        ctx.textual.text     # Textual TUI components
+        ctx.textual.panel
+        ctx.textual.spacer
+        ctx.textual.prompts
+    """
+
+    # Core dependencies
+    secrets: SecretManager
+
+    # Textual TUI components (for TUI mode)
+    textual: Optional[Any] = None
+
+    # Plugin registry
+    plugin_manager: Optional[Any] = None
+
+    # Service clients (populated by builder)
+    ai: Optional[Any] = None
+    git: Optional[Any] = None
+    github: Optional[Any] = None
+    jira: Optional[Any] = None
+
+    # Workflow metadata (set by executor)
+    workflow_name: Optional[str] = None
+    current_step: Optional[int] = None
+    total_steps: Optional[int] = None
+
+    # Shared data storage between steps
+    data: Dict[str, Any] = field(default_factory=dict)
+
+    # Internal state for workflow execution
+    _workflow_stack: List[str] = field(default_factory=list)
+
+    def set(self, key: str, value: Any) -> None:
+        """Set shared data."""
+        self.data[key] = value
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Get shared data."""
+        return self.data.get(key, default)
+
+    def has(self, key: str) -> bool:
+        """Check if key exists in shared data."""
+        return key in self.data
+
+    def enter_workflow(self, workflow_name: str):
+        """
+        Track entering a workflow execution to prevent circular dependencies.
+        """
+        if workflow_name in self._workflow_stack:
+            raise ValueError(
+                f"Circular workflow dependency detected: {' -> '.join(self._workflow_stack)} -> {workflow_name}"
+            )
+        self._workflow_stack.append(workflow_name)
+
+    def exit_workflow(self, workflow_name: str):
+        """
+        Track exiting a workflow execution.
+        """
+        if self._workflow_stack and self._workflow_stack[-1] == workflow_name:
+            self._workflow_stack.pop()