galangal-orchestrate 0.13.0__py3-none-any.whl

galangal/__init__.py

@@ -0,0 +1,36 @@
+"""
+Galangal Orchestrate - AI-driven development workflow orchestrator.
+
+A deterministic workflow system that guides AI assistants through
+structured development stages: PM -> DESIGN -> DEV -> TEST -> QA -> REVIEW -> DOCS.
+"""
+
+from galangal.exceptions import (
+    ConfigError,
+    GalangalError,
+    TaskError,
+    ValidationError,
+    WorkflowError,
+)
+from galangal.logging import (
+    WorkflowLogger,
+    configure_logging,
+    get_logger,
+    workflow_logger,
+)
+
+__version__ = "0.13.0"
+
+__all__ = [
+    # Exceptions
+    "GalangalError",
+    "ConfigError",
+    "ValidationError",
+    "WorkflowError",
+    "TaskError",
+    # Logging
+    "configure_logging",
+    "get_logger",
+    "WorkflowLogger",
+    "workflow_logger",
+]

galangal/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for `python -m galangal`."""
+
+from galangal.cli import main
+
+if __name__ == "__main__":
+    main()

galangal/ai/__init__.py

@@ -0,0 +1,167 @@
+"""AI backend abstractions and factory functions."""
+
+from __future__ import annotations
+
+import shutil
+from typing import TYPE_CHECKING
+
+from galangal.ai.base import AIBackend
+from galangal.ai.claude import ClaudeBackend
+from galangal.ai.codex import CodexBackend
+
+if TYPE_CHECKING:
+    from galangal.config.schema import AIBackendConfig, GalangalConfig
+    from galangal.core.state import Stage
+
+# Registry of available backends
+BACKEND_REGISTRY: dict[str, type[AIBackend]] = {
+    "claude": ClaudeBackend,
+    "codex": CodexBackend,
+}
+
+# Default fallback chain: backend -> fallback
+DEFAULT_FALLBACKS: dict[str, str] = {
+    "codex": "claude",
+    "gemini": "claude",
+}
+
+
+def get_backend(
+    name: str,
+    config: GalangalConfig | None = None,
+) -> AIBackend:
+    """
+    Factory function to instantiate backends by name.
+
+    Args:
+        name: Backend name (e.g., "claude", "codex")
+        config: Optional project config to get backend-specific settings
+
+    Returns:
+        Instantiated backend with configuration
+
+    Raises:
+        ValueError: If backend name is unknown
+    """
+    backend_class = BACKEND_REGISTRY.get(name.lower())
+    if not backend_class:
+        available = list(BACKEND_REGISTRY.keys())
+        raise ValueError(f"Unknown backend: {name}. Available: {available}")
+
+    # Get backend-specific config if available
+    backend_config: AIBackendConfig | None = None
+    if config:
+        backend_config = config.ai.backends.get(name.lower())
+
+    return backend_class(backend_config)
+
+
+def is_backend_available(
+    name: str,
+    config: GalangalConfig | None = None,
+) -> bool:
+    """
+    Check if a backend's CLI tool is available on the system.
+
+    Args:
+        name: Backend name (e.g., "claude", "codex")
+        config: Optional project config to get custom command names
+
+    Returns:
+        True if the backend's CLI is installed and accessible
+    """
+    # Check config for custom command name
+    cmd: str | None
+    if config and name.lower() in config.ai.backends:
+        cmd = config.ai.backends[name.lower()].command
+    else:
+        # Fallback to default command names
+        cli_commands = {
+            "claude": "claude",
+            "codex": "codex",
+            "gemini": "gemini",  # Future
+        }
+        cmd = cli_commands.get(name.lower())
+
+    if not cmd:
+        return False
+    return shutil.which(cmd) is not None
+
+
+def get_backend_with_fallback(
+    name: str,
+    fallbacks: dict[str, str] | None = None,
+    config: GalangalConfig | None = None,
+) -> AIBackend:
+    """
+    Get a backend, falling back to alternatives if unavailable.
+
+    Args:
+        name: Primary backend name
+        fallbacks: Optional custom fallback mapping. Defaults to DEFAULT_FALLBACKS.
+        config: Optional project config for backend settings
+
+    Returns:
+        The requested backend if available, otherwise the fallback backend
+
+    Raises:
+        ValueError: If neither primary nor fallback backends are available
+    """
+    fallbacks = fallbacks or DEFAULT_FALLBACKS
+
+    if is_backend_available(name, config):
+        return get_backend(name, config)
+
+    # Try fallback
+    fallback_name = fallbacks.get(name.lower())
+    if fallback_name and is_backend_available(fallback_name, config):
+        return get_backend(fallback_name, config)
+
+    # Last resort: try claude if it exists
+    if name.lower() != "claude" and is_backend_available("claude", config):
+        return get_backend("claude", config)
+
+    raise ValueError(f"Backend '{name}' not available and no fallback found")
+
+
+def get_backend_for_stage(
+    stage: Stage,
+    config: GalangalConfig,
+    use_fallback: bool = True,
+) -> AIBackend:
+    """
+    Get the appropriate backend for a specific stage.
+
+    Checks config.ai.stage_backends for stage-specific overrides,
+    otherwise uses config.ai.default.
+
+    Args:
+        stage: The workflow stage
+        config: Project configuration
+        use_fallback: If True, fall back to alternative backends if primary unavailable
+
+    Returns:
+        The configured backend for the stage
+    """
+    # Check for stage-specific backend override
+    stage_key = stage.value.upper()
+    if stage_key in config.ai.stage_backends:
+        backend_name = config.ai.stage_backends[stage_key]
+    else:
+        backend_name = config.ai.default
+
+    if use_fallback:
+        return get_backend_with_fallback(backend_name, config=config)
+    return get_backend(backend_name, config)
+
+
+__all__ = [
+    "AIBackend",
+    "ClaudeBackend",
+    "CodexBackend",
+    "BACKEND_REGISTRY",
+    "get_backend",
+    "get_backend_for_stage",
+    "get_backend_with_fallback",
+    "is_backend_available",
+]

galangal/ai/base.py

@@ -0,0 +1,159 @@
+"""
+Abstract base class for AI backends.
+"""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from abc import ABC, abstractmethod
+from collections.abc import Callable, Generator
+from contextlib import contextmanager
+from typing import TYPE_CHECKING
+
+from galangal.results import StageResult
+
+if TYPE_CHECKING:
+    from galangal.config.schema import AIBackendConfig
+    from galangal.ui.tui import StageUI
+
+# Type alias for pause check callback
+PauseCheck = Callable[[], bool]
+
+
+class AIBackend(ABC):
+    """Abstract base class for AI backends."""
+
+    def __init__(self, config: AIBackendConfig | None = None):
+        """
+        Initialize the backend with optional configuration.
+
+        Args:
+            config: Backend-specific configuration from config.ai.backends.
+                   If None, backend should use sensible defaults.
+        """
+        self._config = config
+
+    @property
+    def config(self) -> AIBackendConfig | None:
+        """Return the backend configuration."""
+        return self._config
+
+    @property
+    def read_only(self) -> bool:
+        """Return whether this backend runs in read-only mode."""
+        return self._config.read_only if self._config else False
+
+    def _substitute_placeholders(self, args: list[str], **kwargs: str | int) -> list[str]:
+        """
+        Substitute placeholders in command arguments.
+
+        Replaces {placeholder} patterns with provided values.
+
+        Args:
+            args: List of argument strings with optional placeholders
+            **kwargs: Placeholder values (e.g., max_turns=200, schema_file="/tmp/s.json")
+
+        Returns:
+            List of arguments with placeholders replaced
+        """
+        result = []
+        for arg in args:
+            for key, value in kwargs.items():
+                arg = arg.replace(f"{{{key}}}", str(value))
+            result.append(arg)
+        return result
+
+    @contextmanager
+    def _temp_file(
+        self,
+        content: str | None = None,
+        suffix: str = ".txt",
+    ) -> Generator[str, None, None]:
+        """
+        Context manager for temporary file creation with automatic cleanup.
+
+        Creates a temporary file, optionally writes content to it, yields the path,
+        and ensures cleanup on exit (even if an exception occurs).
+
+        Args:
+            content: Optional content to write to the file. If None, creates an
+                    empty file (useful for output files written by external processes).
+            suffix: File suffix (default: ".txt")
+
+        Yields:
+            Path to the temporary file
+
+        Example:
+            with self._temp_file(prompt, suffix=".txt") as prompt_file:
+                shell_cmd = f"cat '{prompt_file}' | claude ..."
+                # File is automatically cleaned up after the block
+        """
+        filepath: str | None = None
+        try:
+            if content is not None:
+                # Create file with content
+                with tempfile.NamedTemporaryFile(
+                    mode="w", suffix=suffix, delete=False, encoding="utf-8"
+                ) as f:
+                    f.write(content)
+                    filepath = f.name
+            else:
+                # Create empty file for external process to write
+                fd, filepath = tempfile.mkstemp(suffix=suffix)
+                os.close(fd)
+            yield filepath
+        finally:
+            if filepath and os.path.exists(filepath):
+                try:
+                    os.unlink(filepath)
+                except OSError:
+                    pass
+
+    @abstractmethod
+    def invoke(
+        self,
+        prompt: str,
+        timeout: int = 14400,
+        max_turns: int = 200,
+        ui: StageUI | None = None,
+        pause_check: PauseCheck | None = None,
+        stage: str | None = None,
+        log_file: str | None = None,
+    ) -> StageResult:
+        """
+        Invoke the AI with a prompt for a full stage execution.
+
+        Args:
+            prompt: The full prompt to send
+            timeout: Maximum time in seconds
+            max_turns: Maximum conversation turns
+            ui: Optional TUI for progress display
+            pause_check: Optional callback that returns True if pause requested
+            stage: Optional stage name for backends that customize behavior per stage
+            log_file: Optional path to log file for streaming output
+
+        Returns:
+            StageResult with success/failure and structured outcome type
+        """
+        pass
+
+    @abstractmethod
+    def generate_text(self, prompt: str, timeout: int = 30) -> str:
+        """
+        Simple text generation (for PR titles, commit messages, task names).
+
+        Args:
+            prompt: The prompt to send
+            timeout: Maximum time in seconds
+
+        Returns:
+            Generated text, or empty string on failure
+        """
+        pass
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Return the backend name."""
+        pass