titan-cli 0.1.0__py3-none-any.whl

titan_cli/core/config.py

@@ -0,0 +1,274 @@
+# core/config.py
+from pathlib import Path
+from typing import Optional, List
+import tomli
+from .models import TitanConfigModel
+from .plugins.plugin_registry import PluginRegistry
+from .workflows import WorkflowRegistry, ProjectStepSource
+from .secrets import SecretManager
+from .errors import ConfigParseError, ConfigWriteError
+
+class TitanConfig:
+    """Manages Titan configuration with global + project merge"""
+
+    GLOBAL_CONFIG = Path.home() / ".titan" / "config.toml"
+
+    def __init__(
+        self,
+        registry: Optional[PluginRegistry] = None,
+        global_config_path: Optional[Path] = None
+    ):
+        # Core dependencies
+        self.registry = registry or PluginRegistry()
+
+        # These are initialized in load() after config is read
+        self.secrets = None  # Set by load()
+        self._project_root = None  # Set by load()
+        self._active_project_path = None  # Set by load()
+        self._workflow_registry = None  # Set by load()
+        self._plugin_warnings = []
+
+        # Use custom global config path if provided (for testing), otherwise use default
+        self._global_config_path = global_config_path or self.GLOBAL_CONFIG
+
+        # Initial load
+        self.load()
+
+    def load(self):
+        """
+        Reloads the entire configuration from disk, including global config
+        and the project config from the current working directory.
+        """
+        # Load global config
+        self.global_config = self._load_toml(self._global_config_path)
+
+        # Set project root to current working directory
+        self._project_root = Path.cwd()
+        self._active_project_path = Path.cwd()
+
+        # Look for project config in current directory
+        self.project_config_path = self._find_project_config(Path.cwd())
+
+        # Load project config if it exists
+        self.project_config = self._load_toml(self.project_config_path)
+
+        # Merge and validate final config
+        merged = self._merge_configs(self.global_config, self.project_config)
+        self.config = TitanConfigModel(**merged)
+
+        # Re-initialize dependencies that depend on the final config
+        # Use current working directory for secrets
+        secrets_path = Path.cwd()
+        self.secrets = SecretManager(project_path=secrets_path if secrets_path.is_dir() else None)
+
+        # Reset and re-initialize plugins
+        self.registry.reset()
+        self.registry.initialize_plugins(config=self, secrets=self.secrets)
+        self._plugin_warnings = self.registry.list_failed()
+
+        # Re-initialize WorkflowRegistry
+        # Use current working directory for workflows
+        workflow_path = Path.cwd()
+        project_step_source = ProjectStepSource(project_root=workflow_path)
+        self._workflow_registry = WorkflowRegistry(
+            project_root=workflow_path,
+            plugin_registry=self.registry,
+            project_step_source=project_step_source,
+            config=self
+        )
+
+
+    def _find_project_config(self, start_path: Optional[Path] = None) -> Optional[Path]:
+        """Search for .titan/config.toml up the directory tree"""
+        current = (start_path or Path.cwd()).resolve()
+
+        # In a test environment, Path.cwd() might not be under /home/
+        # and we need a stopping condition.
+        sentinel = Path(current.root)
+        
+        while current != current.parent and current != sentinel:
+            config_path = current / ".titan" / "config.toml"
+            if config_path.exists():
+                return config_path
+            current = current.parent
+
+        return None
+
+    def _load_toml(self, path: Optional[Path]) -> dict:
+        """Load TOML file, returning an empty dict on failure."""
+        if not path or not path.exists():
+            return {}
+
+        with open(path, "rb") as f:
+            try:
+                return tomli.load(f)
+            except tomli.TOMLDecodeError as e:
+                # Wrap the generic exception. Warnings will be handled by CLI commands.
+                _ = ConfigParseError(file_path=str(path), original_exception=e)
+                return {}
+
+    def _merge_configs(self, global_cfg: dict, project_cfg: dict) -> dict:
+        """Merge global and project configs (project overrides global)"""
+        merged = {**global_cfg}
+
+        # Project config overrides global
+        for key, value in project_cfg.items():
+            if key == "plugins" and isinstance(value, dict):
+                merged_plugins = merged.setdefault("plugins", {})
+
+                for plugin_name, plugin_data_project in value.items():
+                    plugin_data_global = merged_plugins.get(plugin_name, {})
+
+                    # Start with a copy of the global plugin config for this specific plugin
+                    # This ensures all global settings (like 'enabled') are carried over
+                    # unless explicitly overridden.
+                    final_plugin_data = {**plugin_data_global}
+
+                    # Merge top-level keys from project config, excluding 'config'
+                    for pk, pv in plugin_data_project.items():
+                        if pk != "config":
+                            final_plugin_data[pk] = pv
+
+                    # Handle the nested 'config' dictionary separately (deep merge)
+                    config_section_global = plugin_data_global.get("config", {})
+                    config_section_project = plugin_data_project.get("config", {})
+
+                    if config_section_global or config_section_project:
+                        final_plugin_data["config"] = {**config_section_global, **config_section_project}
+                    elif "config" in final_plugin_data: # If global had a config, and project didn't touch it
+                         pass # Keep the global config
+
+                    merged_plugins[plugin_name] = final_plugin_data
+            elif key == "ai" and isinstance(value, dict):
+                # AI config should be merged intelligently (global + project)
+                # Global AI config is always available, project can override specific settings
+                merged_ai = merged.setdefault("ai", {})
+
+                # Merge providers (project providers supplement global providers)
+                if "providers" in value:
+                    merged_providers = merged_ai.setdefault("providers", {})
+                    # Deep merge: preserve global fields, override with project fields
+                    for provider_id, provider_data in value["providers"].items():
+                        if provider_id in merged_providers:
+                            # Provider exists in global: deep merge (extend, not replace)
+                            merged_providers[provider_id] = {**merged_providers[provider_id], **provider_data}
+                        else:
+                            # New provider: just add it
+                            merged_providers[provider_id] = provider_data
+
+                # Project can override default provider, otherwise keep global
+                if "default" in value:
+                    merged_ai["default"] = value["default"]
+
+                # Merge any other AI settings
+                for ai_key, ai_value in value.items():
+                    if ai_key not in ("providers", "default"):
+                        merged_ai[ai_key] = ai_value
+            else:
+                merged[key] = value
+
+        return merged
+
+    @property
+    def project_root(self) -> Path:
+        """Return the resolved project root path."""
+        return self._project_root
+
+    @property
+    def active_project_path(self) -> Optional[Path]:
+        """Return the path to the currently active project."""
+        return self._active_project_path
+
+    @property
+    def workflows(self) -> WorkflowRegistry:
+        """Access to workflow registry."""
+        return self._workflow_registry
+
+
+    def get_enabled_plugins(self) -> List[str]:
+        """Get list of enabled plugins"""
+        if not self.config or not self.config.plugins:
+            return []
+        return [
+            name for name, plugin_cfg in self.config.plugins.items()
+            if plugin_cfg.enabled
+        ]
+
+    def get_plugin_warnings(self) -> List[str]:
+        """Get list of failed or misconfigured plugins."""
+        return self._plugin_warnings
+
+    def get_project_name(self) -> Optional[str]:
+        """Get the current project name from project config."""
+        if self.config and self.config.project:
+            return self.config.project.name
+        return None
+
+    def _save_global_config(self):
+        """Saves the current state of the global config to disk."""
+        if not self._global_config_path.parent.exists():
+            try:
+                self._global_config_path.parent.mkdir(parents=True)
+            except OSError as e:
+                raise ConfigWriteError(file_path=str(self._global_config_path), original_exception=e)
+
+        existing_global_config = {}
+        if self._global_config_path.exists():
+            try:
+                with open(self._global_config_path, "rb") as f:
+                    import tomllib
+                    existing_global_config = tomllib.load(f)
+            except Exception:
+                pass
+
+        # Save only AI configuration to global config
+        # Project-specific settings are stored in project's .titan/config.toml
+        config_to_save = self.config.model_dump(exclude_none=True)
+
+        if 'ai' in config_to_save:
+            existing_global_config['ai'] = config_to_save['ai']
+
+        try:
+            with open(self._global_config_path, "wb") as f:
+                import tomli_w
+                tomli_w.dump(existing_global_config, f)
+        except ImportError as e:
+            raise ConfigWriteError(file_path=str(self._global_config_path), original_exception=e)
+        except Exception as e:
+            raise ConfigWriteError(file_path=str(self._global_config_path), original_exception=e)
+
+    def is_plugin_enabled(self, plugin_name: str) -> bool:
+        """Check if plugin is enabled"""
+        if not self.config or not self.config.plugins:
+            return False
+        plugin_cfg = self.config.plugins.get(plugin_name)
+        return plugin_cfg.enabled if plugin_cfg else False
+
+    def get_status_bar_info(self) -> dict:
+        """
+        Get information for the status bar display.
+
+        Returns:
+            A dict with keys: 'ai_info', 'project_name'
+            Values are strings or None if not available.
+        """
+        # Extract AI info
+        ai_info = None
+        if self.config and self.config.ai:
+            ai_config = self.config.ai
+            default_provider_id = ai_config.default
+
+            if default_provider_id and default_provider_id in ai_config.providers:
+                provider_config = ai_config.providers[default_provider_id]
+                provider_name = provider_config.provider
+                model = provider_config.model or "default"
+                ai_info = f"{provider_name}/{model}"
+
+        # Extract project name from project config
+        project_name = self.get_project_name()
+
+        return {
+            'ai_info': ai_info,
+            'project_name': project_name
+        }
+

titan_cli/core/discovery.py

@@ -0,0 +1,51 @@
+"""
+Project Discovery Module
+
+Scans a root directory to find and categorize projects based on whether
+they are configured with Titan.
+"""
+
+from pathlib import Path
+from typing import List, Tuple
+
+def discover_projects(root_path_str: str) -> Tuple[List[Path], List[Path]]:
+    """
+    Scans a root directory and discovers configured and unconfigured projects.
+
+    An "unconfigured" project is identified as a directory containing a .git folder.
+    A "configured" project is one that also contains a .titan/config.toml file.
+
+    Args:
+        root_path_str: The absolute path to the root directory to scan.
+
+    Returns:
+        A tuple containing two lists:
+        - A list of paths to configured projects.
+        - A list of paths to unconfigured projects.
+    """
+    configured_projects: List[Path] = []
+    unconfigured_projects: List[Path] = []
+
+    root_path = Path(root_path_str).expanduser().resolve()
+    if not root_path.is_dir():
+        return [], []
+
+    # Iterate through items in the root directory
+    for item in root_path.iterdir():
+        try:
+            # We only care about directories
+            if item.is_dir():
+                is_git_repo = (item / ".git").is_dir()
+                is_titan_project = (item / ".titan" / "config.toml").is_file()
+
+                if is_titan_project:
+                    # If it has a titan config, it's definitely a configured project
+                    configured_projects.append(item)
+                elif is_git_repo:
+                    # If it's a git repo but not a titan project, it's unconfigured
+                    unconfigured_projects.append(item)
+        except PermissionError:
+            # Skip directories we don't have permission to access
+            continue
+
+    return sorted(configured_projects), sorted(unconfigured_projects)

titan_cli/core/errors.py

@@ -0,0 +1,81 @@
+"""
+Custom Exception Types for Titan CLI
+"""
+from ..messages import msg
+
+class TitanError(Exception):
+    """Base exception for all application-specific errors."""
+    pass
+
+class PluginError(TitanError):
+    """Base exception for plugin-related errors."""
+    pass
+
+class PluginLoadError(PluginError):
+    """Raised when a plugin fails to load from an entry point."""
+    def __init__(self, plugin_name: str, original_exception: Exception):
+        self.plugin_name = plugin_name
+        self.original_exception = original_exception
+        # Do not call super().__init__ with message here, as it's formatted by __str__
+
+    def __str__(self) -> str:
+        return msg.Errors.PLUGIN_LOAD_FAILED.format(
+            plugin_name=self.plugin_name, 
+            error=str(self.original_exception)
+        )
+
+class PluginInitializationError(PluginError):
+    """Raised when a plugin fails to initialize."""
+
+    def __init__(self, plugin_name: str, original_exception: Exception):
+        self.plugin_name = plugin_name
+        self.original_exception = original_exception
+        # Do not call super().__init__ with message here, as it's formatted by __str__
+
+    def __str__(self) -> str:
+        return msg.Errors.PLUGIN_INIT_FAILED.format(
+            plugin_name=self.plugin_name,
+            error=str(self.original_exception)
+        )
+
+class ConfigError(TitanError):
+    """Base exception for configuration-related errors."""
+    pass
+
+class ConfigNotFoundError(ConfigError, FileNotFoundError):
+    """Raised when a config file cannot be found."""
+    pass
+
+class ConfigParseError(ConfigError):
+
+    """Raised when a config file cannot be parsed."""
+
+    def __init__(self, file_path: str, original_exception: Exception):
+
+        self.file_path = file_path
+        self.original_exception = original_exception
+
+        message = msg.Errors.CONFIG_PARSE_ERROR.format(
+            file_path=file_path,
+            error=original_exception
+        )
+
+        super().__init__(message)
+
+
+
+class ConfigWriteError(ConfigError):
+
+    """Raised when writing to a configuration file fails."""
+
+    def __init__(self, file_path: str, original_exception: Exception):
+
+        self.file_path = file_path
+        self.original_exception = original_exception
+
+        message = msg.Errors.CONFIG_WRITE_FAILED.format(
+            path=file_path,
+            error=original_exception
+        )
+
+        super().__init__(message)

titan_cli/core/models.py

@@ -0,0 +1,52 @@
+# core/models.py
+from pydantic import BaseModel, Field, model_validator
+from typing import Optional, Dict
+from .plugins.models import PluginConfig
+
+class ProjectConfig(BaseModel):
+    """
+    Represents the configuration for a specific project.
+    Defined in .titan/config.toml.
+    """
+    name: str = Field(..., description="Name of the project.")
+    type: Optional[str] = Field("generic", description="Type of the project (e.g., 'fullstack', 'backend', 'frontend').")
+
+class AIProviderConfig(BaseModel):
+    """Configuración de un provider específico"""
+    name: str = Field(..., description="Nombre del provider (ej: 'Corporate Gemini')")
+    type: str = Field(..., description="'corporate' o 'individual'")
+    provider: str = Field(..., description="'anthropic', 'gemini', 'openai'")
+    model: Optional[str] = Field(None, description="Modelo a usar")
+    base_url: Optional[str] = Field(None, description="URL custom (solo corporate)")
+    max_tokens: int = Field(4096)
+    temperature: float = Field(0.7)
+
+class AIConfig(BaseModel):
+    """
+    Represents the configuration for AI provider integration.
+    Can be defined globally or per project.
+    """
+    default: str = Field("default", description="ID del provider por defecto")
+    providers: Dict[str, AIProviderConfig] = Field(default_factory=dict)
+
+    @model_validator(mode='before')
+    def validate_default_provider(cls, values):
+        default_provider = values.get('default')
+        providers = values.get('providers')
+
+        if default_provider and providers:
+            if default_provider not in providers:
+                raise ValueError(f"Default provider '{default_provider}' not found in configured providers.")
+        elif default_provider and not providers:
+            raise ValueError("Cannot set a default provider when no providers are configured.")
+        return values
+
+class TitanConfigModel(BaseModel):
+    """
+    The main Pydantic model for the entire Titan CLI configuration.
+    This model validates the merged configuration from global and project sources.
+    """
+    project: Optional[ProjectConfig] = Field(None, description="Project-specific configuration.")
+    ai: Optional[AIConfig] = Field(None, description="AI provider configuration.")
+    plugins: Dict[str, PluginConfig] = Field(default_factory=dict, description="Dictionary of plugin configurations.")
+

titan_cli/core/plugins/available.py

@@ -0,0 +1,36 @@
+"""
+This file contains a list of known, installable plugins for Titan CLI.
+
+This acts as a centralized registry for the `install` command, so the CLI
+knows what plugins are available to be installed via `pipx inject`.
+"""
+from typing import TypedDict, List
+
+class KnownPlugin(TypedDict):
+    """Represents a known plugin that can be installed."""
+    name: str
+    description: str
+    package_name: str
+    dependencies: List[str]  # Plugin names that must be installed first
+
+# This list should be updated when new official plugins are published.
+KNOWN_PLUGINS: List[KnownPlugin] = [
+    {
+        "name": "git",
+        "description": "Provides core Git functionalities for workflows.",
+        "package_name": "titan-plugin-git",
+        "dependencies": []
+    },
+    {
+        "name": "github",
+        "description": "Adds GitHub integration for pull requests and more.",
+        "package_name": "titan-plugin-github",
+        "dependencies": ["git"]  # Requires git plugin
+    },
+    {
+        "name": "jira",
+        "description": "JIRA integration for issue management.",
+        "package_name": "titan-plugin-jira",
+        "dependencies": []
+    },
+]

titan_cli/core/plugins/models.py

@@ -0,0 +1,67 @@
+# titan_cli/core/plugins/models.py
+from pydantic import BaseModel, Field, field_validator
+from typing import Dict, Any, Optional
+
+class PluginConfig(BaseModel):
+    """
+    Represents the configuration for an individual plugin.
+    """
+    enabled: bool = Field(True, description="Whether the plugin is enabled.")
+    config: Dict[str, Any] = Field(default_factory=dict, description="Plugin-specific configuration options.")
+
+class GitPluginConfig(BaseModel):
+    """Configuration for Git plugin."""
+    main_branch: str = Field("main", description="Main/default branch name")
+    default_remote: str = Field("origin", description="Default remote name")
+
+class GitHubPluginConfig(BaseModel):
+    """Configuration for GitHub plugin."""
+    repo_owner: str = Field(..., description="GitHub repository owner (user or organization).")
+    repo_name: str = Field(..., description="GitHub repository name.")
+    default_branch: str = Field(None, description="Default branch to use (e.g., 'main', 'develop').")
+    pr_template_path: str = Field(None, description="Path to PR template file relative to repository root (e.g., '.github/pull_request_template.md', 'docs/PR_TEMPLATE.md'). Defaults to '.github/pull_request_template.md'.")
+    auto_assign_prs: bool = Field(True, description="Automatically assign PRs to the author.")
+
+
+class JiraPluginConfig(BaseModel):
+    """
+    Configuration for JIRA plugin.
+
+    Credentials (base_url, email, api_token) should be configured at global level (~/.titan/config.toml).
+    Project-specific settings (default_project) can override at project level (.titan/config.toml).
+    """
+    base_url: Optional[str] = Field(None, description="JIRA instance URL (e.g., 'https://jira.company.com')")
+    email: Optional[str] = Field(None, description="User email for authentication")
+    # api_token is stored in secrets, not in config.toml
+    # It appears in the JSON schema for interactive configuration but is optional in the model
+    api_token: Optional[str] = Field(None, description="JIRA API token (Personal Access Token)", json_schema_extra={"format": "password", "required_in_schema": True})
+    default_project: Optional[str] = Field(None, description="Default JIRA project key (e.g., 'ECAPP', 'PROJ')")
+    timeout: int = Field(30, description="Request timeout in seconds")
+    enable_cache: bool = Field(True, description="Enable caching for API responses")
+    cache_ttl: int = Field(300, description="Cache time-to-live in seconds")
+
+    @field_validator('base_url')
+    @classmethod
+    def validate_base_url(cls, v):
+        """Validate base_url is configured and properly formatted."""
+        if not v:
+            raise ValueError(
+                "JIRA base_url not configured. "
+                "Please add [plugins.jira.config] section with base_url in ~/.titan/config.toml"
+            )
+        if not v.startswith(('http://', 'https://')):
+            raise ValueError("base_url must start with http:// or https://")
+        return v.rstrip('/')  # Normalize trailing slash
+
+    @field_validator('email')
+    @classmethod
+    def validate_email(cls, v):
+        """Validate email is configured and has valid format."""
+        if not v:
+            raise ValueError(
+                "JIRA email not configured. "
+                "Please add [plugins.jira.config] section with email in ~/.titan/config.toml"
+            )
+        if '@' not in v:
+            raise ValueError("email must be a valid email address")
+        return v.lower()  # Normalize email to lowercase

titan_cli/core/plugins/plugin_base.py

@@ -0,0 +1,108 @@
+"""
+Base interface for Titan plugins.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Optional, Dict, Any, Callable
+from pathlib import Path
+
+
+class TitanPlugin(ABC):
+    """
+    Base class for all Titan plugins.
+    
+    Plugins extend Titan CLI with:
+    - Service clients (Git, GitHub, Jira, etc.)
+    - Workflow steps (atomic operations)
+    
+    Example:
+        class GitPlugin(TitanPlugin):
+            @property
+            def name(self) -> str:
+                return "git"
+            
+            def get_client(self):
+                return GitClient()
+    """
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """
+        Plugin unique identifier.
+        
+        Returns:
+            Plugin name (e.g., "git", "github", "jira")
+        """
+        pass
+
+    @property
+    def version(self) -> str:
+        """Plugin version (default: "0.0.0")"""
+        return "0.0.0"
+
+    @property
+    def description(self) -> str:
+        """Plugin description (default: empty)"""
+        return ""
+
+    @property
+    def dependencies(self) -> list[str]:
+        """
+        Other plugins this plugin depends on.
+        
+        Returns:
+            List of plugin names (e.g., ["git"] for GitHub plugin)
+        """
+        return []
+
+    def initialize(self, config: Any, secrets: Any) -> None:
+        """
+        Initialize plugin with configuration and secrets.
+        
+        Called once when plugin is loaded by PluginRegistry.
+        
+        Args:
+            config: TitanConfig instance
+            secrets: SecretManager instance
+        """
+        pass
+
+    def get_client(self) -> Optional[Any]:
+        """
+        Get the main client instance for this plugin.
+        
+        This client will be injected into WorkflowContext.
+        
+        Returns:
+            Client instance or None
+        """
+        return None
+
+    def get_steps(self) -> Dict[str, Callable]:
+        """
+        Get workflow steps provided by this plugin.
+        
+        Returns:
+            Dict mapping step name to step function
+        """
+        return {}
+
+    def is_available(self) -> bool:
+        """
+        Check if plugin is available/configured.
+        
+        Returns:
+            True if plugin can be used
+        """
+        return True
+
+    @property
+    def workflows_path(self) -> Optional[Path]:
+        """
+        Optional path to the directory containing workflow definitions for this plugin.
+        
+        Returns:
+            Path to workflows directory or None if the plugin doesn't provide any.
+        """
+        return None