titan-cli 0.1.0__py3-none-any.whl

titan_cli/core/plugins/plugin_registry.py

@@ -0,0 +1,163 @@
+# core/plugin_registry.py
+from importlib.metadata import entry_points
+from typing import Dict, List, Any, Optional
+from ..errors import PluginLoadError, PluginInitializationError
+from .plugin_base import TitanPlugin
+
+class PluginRegistry:
+    """Discovers and manages installed plugins."""
+
+    def __init__(self, discover_on_init: bool = True):
+        self._plugins: Dict[str, TitanPlugin] = {}
+        self._failed_plugins: Dict[str, Exception] = {}
+        self._discovered_plugin_names: List[str] = []
+        if discover_on_init:
+            self.discover()
+
+    def discover(self):
+        """Discover all installed Titan plugins."""
+        import logging
+        logger = logging.getLogger('titan_cli.ui.tui.screens.project_setup_wizard')
+
+        discovered = entry_points(group='titan.plugins')
+        self._discovered_plugin_names = [ep.name for ep in discovered]
+        logger.debug(f"PluginRegistry.discover() - Found {len(self._discovered_plugin_names)} plugins: {self._discovered_plugin_names}")
+
+        for ep in discovered:
+            try:
+                logger.debug(f"Loading plugin: {ep.name}")
+                plugin_class = ep.load()
+                if not issubclass(plugin_class, TitanPlugin):
+                    raise TypeError("Plugin class must inherit from TitanPlugin")
+                self._plugins[ep.name] = plugin_class()
+                logger.debug(f"Successfully loaded plugin: {ep.name}")
+            except Exception as e:
+                logger.error(f"Failed to load plugin {ep.name}: {e}", exc_info=True)
+                error = PluginLoadError(plugin_name=ep.name, original_exception=e)
+                self._failed_plugins[ep.name] = error
+
+        logger.debug(f"PluginRegistry.discover() - Loaded {len(self._plugins)} plugins successfully")
+        logger.debug(f"PluginRegistry.discover() - Failed {len(self._failed_plugins)} plugins: {list(self._failed_plugins.keys())}")
+
+    def initialize_plugins(self, config: Any, secrets: Any) -> None:
+        """
+        Initializes all discovered plugins in dependency order.
+
+        Args:
+            config: TitanConfig instance
+            secrets: SecretManager instance
+        """
+        import logging
+        logger = logging.getLogger('titan_cli.ui.tui.screens.project_setup_wizard')
+
+        # Create a copy of plugin names to iterate over, as _plugins might change
+        plugins_to_initialize = list(self._plugins.keys())
+        initialized = set()
+
+        # Simple dependency resolution loop
+        while plugins_to_initialize:
+            remaining_plugins_count = len(plugins_to_initialize)
+            next_pass_plugins = []
+
+            for name in plugins_to_initialize:
+                if name in initialized:
+                    continue
+
+                plugin = self._plugins[name]
+                dependencies_met = True
+                
+                # Check if all dependencies are initialized or failed
+                for dep_name in plugin.dependencies:
+                    if dep_name not in initialized:
+                        # If a dependency failed to load/initialize, this plugin also implicitly fails
+                        if dep_name in self._failed_plugins:
+                            # Mark this plugin as failed due to dependency
+                            error = PluginInitializationError(
+                                plugin_name=name,
+                                original_exception=f"Dependency '{dep_name}' failed to load/initialize."
+                            )
+                            self._failed_plugins[name] = error
+                            # Don't delete from _plugins - keep it available for configuration
+                            dependencies_met = False
+                            break
+                        else:
+                            dependencies_met = False
+                            break
+                
+                if not dependencies_met:
+                    if name not in self._failed_plugins: # If not already marked failed by dependency
+                        next_pass_plugins.append(name)
+                    continue
+
+                # Initialize the plugin if dependencies are met
+                try:
+                    logger.debug(f"Initializing plugin: {name}")
+                    plugin.initialize(config, secrets)
+                    initialized.add(name)
+                    logger.debug(f"Successfully initialized plugin: {name}")
+                except Exception as e:
+                    logger.error(f"Failed to initialize plugin {name}: {e}", exc_info=True)
+                    error = PluginInitializationError(plugin_name=name, original_exception=e)
+                    self._failed_plugins[name] = error
+                    # Don't delete from _plugins - keep it available for configuration
+
+            plugins_to_initialize = next_pass_plugins
+            if len(plugins_to_initialize) == remaining_plugins_count and remaining_plugins_count > 0:
+                # Circular dependency or unresolvable dependency
+                for name in plugins_to_initialize:
+                    if name not in self._failed_plugins: # Only mark if not already failed by dependency
+                        error = PluginInitializationError(
+                            plugin_name=name,
+                            original_exception="Circular or unresolvable dependency detected."
+                        )
+                        self._failed_plugins[name] = error
+                        if name in self._plugins: # Only delete if it wasn't deleted by a dep error
+                            del self._plugins[name]
+                break # Exit the loop if no progress is made
+
+    def list_installed(self) -> List[str]:
+        """List successfully loaded plugins."""
+        return list(self._plugins.keys())
+
+    def list_discovered(self) -> List[str]:
+        """List all discovered plugins by name, regardless of load status."""
+        return self._discovered_plugin_names
+
+    def list_enabled(self, config: Any) -> List[str]:
+        """
+        List plugins that are enabled in the current project configuration.
+
+        Args:
+            config: TitanConfig instance
+
+        Returns:
+            List of enabled plugin names
+        """
+        if not config or not config.config or not config.config.plugins:
+            return []
+
+        enabled = []
+        for plugin_name, plugin_config in config.config.plugins.items():
+            if hasattr(plugin_config, 'enabled') and plugin_config.enabled:
+                enabled.append(plugin_name)
+
+        return enabled
+
+    def list_failed(self) -> Dict[str, Exception]:
+        """
+        List plugins that failed to load or initialize.
+
+        Returns:
+            Dict mapping plugin name to error
+        """
+        return self._failed_plugins.copy()
+
+    def get_plugin(self, name: str) -> Optional[TitanPlugin]:
+        """Get plugin instance by name."""
+        return self._plugins.get(name)
+
+    def reset(self):
+        """Resets the registry, clearing all loaded plugins and re-discovering."""
+        self._plugins.clear()
+        self._failed_plugins.clear()
+        self.discover()

titan_cli/core/secrets.py

@@ -0,0 +1,141 @@
+# titan_cli/core/secrets.py
+import os
+import keyring
+from pathlib import Path
+from typing import Optional, Literal
+from dotenv import load_dotenv
+
+ScopeType = Literal["env", "project", "user"]
+
+class SecretManager:
+    """
+    Manages secrets with a 3-level cascade:
+
+    1. Environment variables (HIGHEST - CI/CD)
+    2. Project secrets (.titan/secrets.env - team-shared)
+    3. System keyring (USER - personal credentials)
+    """
+
+    def __init__(self, project_path: Optional[Path] = None):
+        self.project_path = project_path or Path.cwd()
+        self._load_project_secrets()
+
+    def _load_project_secrets(self):
+        """Load secrets from .titan/secrets.env"""
+        secrets_file = self.project_path / ".titan" / "secrets.env"
+        if secrets_file.exists():
+            load_dotenv(secrets_file)
+
+    def get(self, key: str, namespace: str = "titan") -> Optional[str]:
+        """
+        Get secret with cascading priority
+
+        Priority:
+        1. Environment variable (e.g., GITHUB_TOKEN, includes project secrets loaded at init)
+        2. System keyring (user-level)
+        3. None
+
+        Note: Project secrets (.titan/secrets.env) are loaded
+        into environment on init, so they are checked in step 1.
+        """
+        # 1. Environment variable (includes project secrets)
+        env_key = key.upper()
+        if env_key in os.environ:
+            return os.environ[env_key]
+
+        # 2. System keyring
+        try:
+            value = keyring.get_password(namespace, key)
+            if value:
+                return value
+        except Exception:
+            pass  # Keyring might not be available
+
+        return None
+
+    def set(
+        self,
+        key: str,
+        value: str,
+        namespace: str = "titan",
+        scope: ScopeType = "user"
+    ):
+        """
+        Set secret
+
+        Args:
+            key: Secret key (e.g., "anthropic_api_key")
+            value: Secret value
+            namespace: Keyring namespace
+            scope: Where to store:
+                - "env": Current environment only (temporary)
+                - "project": .titan/secrets.env (team-shared)
+                - "user": System keyring (personal, secure)
+        """
+        if scope == "env":
+            # Set in current environment only
+            os.environ[key.upper()] = value
+
+        elif scope == "user":
+            # Store in system keyring (most secure)
+            try:
+                keyring.set_password(namespace, key, value)
+            except Exception:
+                # Fallback to project scope if keyring fails (common on macOS with unsigned apps)
+                # Recursively call with project scope
+                self.set(key, value, scope="project")
+
+        elif scope == "project":
+            # Store in .titan/secrets.env
+            secrets_file = self.project_path / ".titan" / "secrets.env"
+            secrets_file.parent.mkdir(parents=True, exist_ok=True)
+
+            # Read existing content
+            existing_lines = []
+            if secrets_file.exists():
+                with open(secrets_file, "r") as f:
+                    existing_lines = f.readlines()
+
+            # Update or append
+            key_upper = key.upper()
+            updated = False
+            for i, line in enumerate(existing_lines):
+                if line.startswith(f"{key_upper}="):
+                    existing_lines[i] = f"{key_upper}='{value}'\n"
+                    updated = True
+                    break
+
+            if not updated:
+                existing_lines.append(f"{key_upper}='{value}'\n")
+
+            # Write back
+            with open(secrets_file, "w") as f:
+                f.writelines(existing_lines)
+
+    def delete(self, key: str, namespace: str = "titan", scope: ScopeType = "user"):
+        """Delete secret from specified scope"""
+        if scope == "env":
+            env_key = key.upper()
+            os.environ.pop(env_key, None)
+
+        elif scope == "user":
+            try:
+                keyring.delete_password(namespace, key)
+            except Exception:
+                pass # Keyring might not be available
+
+        elif scope == "project":
+            secrets_file = self.project_path / ".titan" / "secrets.env"
+            if not secrets_file.exists():
+                return
+
+            # Read and filter
+            with open(secrets_file, "r") as f:
+                lines = f.readlines()
+
+            key_upper = key.upper()
+            filtered = [line for line in lines if not line.startswith(f"{key_upper}=")]
+
+            # Write back
+            with open(secrets_file, "w") as f:
+                f.writelines(filtered)

titan_cli/core/workflows/__init__.py

@@ -0,0 +1,22 @@
+# titan_cli/core/workflows/__init__.py
+"""
+Workflow management system.
+
+Similar to plugins system, but for workflows:
+- WorkflowRegistry: Discover and manage workflows
+- WorkflowSource: Load from multiple sources (project, user, system, plugins)
+"""
+
+from .workflow_registry import WorkflowRegistry, ParsedWorkflow
+from .workflow_sources import WorkflowInfo
+from .workflow_exceptions import WorkflowNotFoundError, WorkflowExecutionError
+from .project_step_source import ProjectStepSource
+
+__all__ = [
+    "WorkflowRegistry",
+    "WorkflowInfo",
+    "ParsedWorkflow",
+    "WorkflowNotFoundError",
+    "WorkflowExecutionError",
+    "ProjectStepSource",
+]

titan_cli/core/workflows/models.py

@@ -0,0 +1,88 @@
+from typing import Any, Dict, List, Literal, Optional, Union
+from pydantic import BaseModel, Field, model_validator
+
+class WorkflowStepModel(BaseModel):
+    """
+    Represents a single step in a workflow.
+    """
+    id: Optional[str] = Field(None, description="Unique identifier for the step. Auto-generated from name if not provided.")
+    name: Optional[str] = Field(None, description="Human-readable name for the step.")
+    plugin: Optional[str] = Field(None, description="The plugin providing the step (e.g., 'git', 'github').")
+    step: Optional[str] = Field(None, description="The name of the step function within the plugin.")
+    command: Optional[str] = Field(None, description="A shell command to execute.")
+    workflow: Optional[str] = Field(None, description="The name of another workflow to execute.")
+    params: Dict[str, Any] = Field(default_factory=dict, description="Parameters to pass to the step or command.")
+    on_error: Literal["fail", "continue"] = Field("fail", description="Action to take if the step fails.")
+    use_shell: bool = Field(False, description="If true, execute the command in a shell. WARNING: This can be a security risk if the command uses untrusted input.")
+
+    # Used only in base workflow definitions to mark injection points for hooks
+    hook: Optional[str] = Field(None, description="Marks this step as a hook point for extension.")
+
+    @model_validator(mode='after')
+    def validate_step_type(self):
+        """
+        Validate that the step has exactly one of: (plugin + step), command, or workflow.
+        Also auto-generates id from name if not provided.
+        """
+        # Auto-generate id from name if not provided
+        if not self.id:
+            if self.name:
+                # Convert name to valid id: lowercase, replace non-alphanumeric with underscore
+                import re
+                self.id = re.sub(r'[^a-z0-9_]', '_', self.name.lower()).strip('_')
+            elif self.hook:
+                # For hook-only steps, use hook name as id
+                self.id = f"hook_{self.hook}"
+            elif self.plugin and self.step:
+                # For plugin steps, use plugin_step as id
+                self.id = f"{self.plugin}_{self.step}"
+            elif self.workflow:
+                # For workflow steps, use workflow name as id
+                self.id = f"workflow_{self.workflow.replace(':', '_').replace('/', '_')}"
+            elif self.command:
+                # For command steps, generate generic id
+                self.id = "command_step"
+            else:
+                # Fallback
+                self.id = "step"
+
+        # A step can be just a hook, in which case other fields are not needed.
+        if self.hook:
+            return self
+
+        has_plugin_step = self.plugin is not None and self.step is not None
+        has_command = self.command is not None
+        has_workflow = self.workflow is not None
+
+        provided_actions = sum([has_plugin_step, has_command, has_workflow])
+
+        if provided_actions > 1:
+            raise ValueError(f"Step '{self.id}' can only have one action type, but found multiple: "
+                             f"{'plugin/step, ' if has_plugin_step else ''}"
+                             f"{'command, ' if has_command else ''}"
+                             f"{'workflow' if has_workflow else ''}".strip(', '))
+
+        if provided_actions == 0 and not self.hook:
+            raise ValueError(f"Step '{self.id}' must define an action: either (plugin and step), a command, a workflow, or a hook.")
+
+        return self
+
+
+class WorkflowConfigModel(BaseModel):
+    """
+    Represents the overall configuration of a workflow.
+    """
+    name: str = Field(..., description="The name of the workflow.")
+    description: Optional[str] = Field(None, description="A description of what the workflow does.")
+    source: Optional[str] = Field(None, description="Where the workflow is defined (e.g., 'plugin:github').")
+    extends: Optional[str] = Field(None, description="The base workflow this workflow extends.")
+    
+    params: Dict[str, Any] = Field(default_factory=dict, description="Workflow-level parameters that can be overridden.")
+    
+    # For base workflows: list of hook names (e.g., ["before_commit"])
+    # For extending workflows: dict of hook_name -> list of steps to inject
+    # This will be handled during loading/merging by the WorkflowLoader,
+    # so we define it broadly here and refine during processing.
+    hooks: Optional[Union[List[str], Dict[str, List[WorkflowStepModel]]]] = Field(None, description="Hook definitions or steps to inject into hooks.")
+    
+    steps: List[WorkflowStepModel] = Field(default_factory=list, description="The sequence of steps in the workflow.")

titan_cli/core/workflows/project_step_source.py

@@ -0,0 +1,86 @@
+import importlib.util
+from pathlib import Path
+from typing import Callable, Dict, Any, Optional, List
+from dataclasses import dataclass
+
+from titan_cli.engine.context import WorkflowContext
+from titan_cli.engine.results import WorkflowResult
+
+# Define a type alias for a Step Function
+StepFunction = Callable[[WorkflowContext, Dict[str, Any]], WorkflowResult]
+
+@dataclass
+class StepInfo:
+    """
+    Metadata for a discovered project step.
+    """
+    name: str
+    path: Path
+    
+class ProjectStepSource:
+    """
+    Discovers and loads Python step functions from a project's .titan/steps/ directory.
+    """
+    def __init__(self, project_root: Path):
+        self._project_root = project_root
+        self._steps_dir = self._project_root / ".titan" / "steps"
+        self._step_info_cache: Optional[List[StepInfo]] = None
+        self._step_function_cache: Dict[str, StepFunction] = {}
+
+    EXCLUDED_FILES = {"__init__.py", "__pycache__"}
+
+    def discover(self) -> List[StepInfo]:
+        """
+        Discovers all available step files in the project's .titan/steps directory.
+        """
+        if self._step_info_cache is not None:
+            return self._step_info_cache
+
+        if not self._steps_dir.is_dir():
+            self._step_info_cache = []
+            return []
+
+        discovered = []
+        for step_file in self._steps_dir.glob("*.py"):
+            if step_file.name not in self.EXCLUDED_FILES:
+                step_name = step_file.stem
+                discovered.append(StepInfo(name=step_name, path=step_file))
+        
+        self._step_info_cache = discovered
+        return discovered
+
+    def get_step(self, step_name: str) -> Optional[StepFunction]:
+        """
+        Retrieves a step function by name, loading it from its file if necessary.
+        """
+        if step_name in self._step_function_cache:
+            return self._step_function_cache[step_name]
+
+        # Find the step info from the discovered list
+        discovered_steps = self.discover()
+        step_info = next((s for s in discovered_steps if s.name == step_name), None)
+
+        if not step_info:
+            return None
+
+        try:
+            spec = importlib.util.spec_from_file_location(step_name, step_info.path)
+            if spec and spec.loader:
+                module = importlib.util.module_from_spec(spec)
+                spec.loader.exec_module(module)
+                
+                # Convention: the step function has the same name as the file
+                step_func = getattr(module, step_name, None)
+                if callable(step_func):
+                    self._step_function_cache[step_name] = step_func
+                    return step_func
+                else:
+                    # Optional: Log a warning if a file exists but the function doesn't
+                    pass
+                    
+        except Exception as e:
+            # Optional: Log a more detailed error
+            print(f"Error loading project step '{step_name}': {e}")
+
+        return None
+

titan_cli/core/workflows/workflow_exceptions.py

@@ -0,0 +1,17 @@
+from titan_cli.core.errors import TitanError
+
+class WorkflowError(TitanError):
+    """Base exception for workflow-related errors."""
+    pass
+
+class WorkflowNotFoundError(WorkflowError):
+    """Raised when a workflow or its base cannot be found."""
+    pass
+
+class WorkflowValidationError(WorkflowError):
+    """Raised when a workflow configuration fails Pydantic validation."""
+    pass
+
+class WorkflowExecutionError(WorkflowError):
+    """Raised when a workflow execution fails."""
+    pass

titan_cli/core/workflows/workflow_filter_service.py

@@ -0,0 +1,137 @@
+"""
+Workflow Filter Service
+
+Service for filtering and grouping workflows by plugin.
+"""
+from typing import Dict, List, Set
+
+from .workflow_sources import WorkflowInfo
+
+
+class WorkflowFilterService:
+    """Service for filtering and grouping workflows."""
+
+    @staticmethod
+    def detect_plugin_name(wf_info: WorkflowInfo) -> str:
+        """
+        Detect the actual plugin name for a workflow.
+
+        This method intelligently detects which plugin a workflow belongs to,
+        even for project/user workflows that use plugin steps.
+
+        Args:
+            wf_info: WorkflowInfo object to analyze
+
+        Returns:
+            Plugin name in capitalized form (e.g., "Github", "Jira", "Custom")
+
+        Examples:
+            Plugin workflow: "plugin:github" -> "Github"
+            Project workflow using GitHub steps -> "Github"
+            Project workflow using Jira steps -> "Jira"
+            Project workflow with no plugins -> "Custom"
+        """
+        # If it's already from a plugin, extract the name
+        if wf_info.source.startswith("plugin:"):
+            plugin_name = wf_info.source.split(":", 1)[1]
+            return plugin_name.capitalize()
+
+        # For project/user workflows, check which plugin they use
+        if wf_info.source in ["project", "user"]:
+            if wf_info.required_plugins:
+                # Use the first required plugin (most workflows use only one)
+                primary_plugin = sorted(wf_info.required_plugins)[0]
+                return primary_plugin.capitalize()
+            else:
+                # No plugin dependencies, it's a custom workflow
+                return "Custom"
+
+        # Fallback for other sources
+        return wf_info.source.capitalize()
+
+    @staticmethod
+    def group_by_plugin(workflows: List[WorkflowInfo]) -> Dict[str, List[WorkflowInfo]]:
+        """
+        Group workflows by their associated plugin.
+
+        Analyzes each workflow to determine its plugin and creates a mapping
+        from plugin names to lists of workflows.
+
+        Args:
+            workflows: List of WorkflowInfo objects to group
+
+        Returns:
+            Dictionary mapping plugin names to lists of workflows
+
+        Example:
+            {
+                "Github": [workflow1, workflow2],
+                "Jira": [workflow3],
+                "Custom": [workflow4]
+            }
+        """
+        plugin_map: Dict[str, List[WorkflowInfo]] = {}
+
+        for wf_info in workflows:
+            plugin_name = WorkflowFilterService.detect_plugin_name(wf_info)
+
+            if plugin_name not in plugin_map:
+                plugin_map[plugin_name] = []
+            plugin_map[plugin_name].append(wf_info)
+
+        return plugin_map
+
+    @staticmethod
+    def get_unique_plugin_names(workflows: List[WorkflowInfo]) -> Set[str]:
+        """
+        Get all unique plugin names from a list of workflows.
+
+        Args:
+            workflows: List of WorkflowInfo objects
+
+        Returns:
+            Set of unique plugin names
+        """
+        plugin_names = set()
+        for wf_info in workflows:
+            plugin_name = WorkflowFilterService.detect_plugin_name(wf_info)
+            plugin_names.add(plugin_name)
+        return plugin_names
+
+    @staticmethod
+    def filter_by_plugin(workflows: List[WorkflowInfo], plugin_name: str) -> List[WorkflowInfo]:
+        """
+        Filter workflows by plugin name.
+
+        Args:
+            workflows: List of WorkflowInfo objects to filter
+            plugin_name: Plugin name to filter by (e.g., "Github")
+
+        Returns:
+            List of workflows that belong to the specified plugin
+        """
+        return [
+            wf for wf in workflows
+            if WorkflowFilterService.detect_plugin_name(wf) == plugin_name
+        ]
+
+    @staticmethod
+    def remove_duplicates(workflows: List[WorkflowInfo]) -> List[WorkflowInfo]:
+        """
+        Remove duplicate workflows by name, keeping first occurrence.
+
+        Args:
+            workflows: List of WorkflowInfo objects that may contain duplicates
+
+        Returns:
+            List of unique workflows (by name)
+        """
+        seen = set()
+        unique_workflows = []
+
+        for wf in workflows:
+            if wf.name not in seen:
+                seen.add(wf.name)
+                unique_workflows.append(wf)
+
+        return unique_workflows