galangal-orchestrate 0.13.0__py3-none-any.whl

galangal/config/defaults.py

@@ -0,0 +1,183 @@
+"""
+Default configuration values and templates.
+"""
+
+DEFAULT_CONFIG_YAML = """\
+# Galangal Orchestrate Configuration
+# https://github.com/Galangal-Media/galangal-orchestrate
+
+project:
+  name: "{project_name}"
+
+# Task storage location
+tasks_dir: galangal-tasks
+
+# Git branch naming pattern
+branch_pattern: "task/{{task_name}}"
+
+# =============================================================================
+# Stage Configuration
+# =============================================================================
+
+stages:
+  # Stages to always skip for this project
+  skip:
+    - BENCHMARK        # Enable if you have performance requirements
+    # - CONTRACT       # Enable if you have OpenAPI contract testing
+    # - MIGRATION      # Uncomment to always skip (auto-skips if no migration files)
+
+  # Stage timeout in seconds (default: 4 hours)
+  timeout: 14400
+
+  # Max retries per stage
+  max_retries: 5
+
+# =============================================================================
+# Validation Commands
+# =============================================================================
+# Configure how each stage validates its outputs.
+# Use {{task_dir}} placeholder for the task artifacts directory.
+
+validation:
+  # Preflight - environment checks (runs directly, no AI)
+  preflight:
+    checks:
+      - name: "Git clean"
+        command: "git status --porcelain"
+        expect_empty: true
+        warn_only: true       # Report but don't fail if working tree has changes
+
+  # Migration - auto-skip if no migration files changed
+  migration:
+    skip_if:
+      no_files_match:
+        - "**/migrations/**"
+        - "**/migrate/**"
+        - "**/alembic/**"
+        - "**/*migration*"
+        - "**/schema/**"
+        - "**/db/migrate/**"
+    artifacts_required:
+      - "MIGRATION_REPORT.md"
+
+  # Contract - API contract validation (auto-skip if no API files changed)
+  contract:
+    skip_if:
+      no_files_match:
+        - "**/api/**"
+        - "**/openapi*"
+        - "**/swagger*"
+        - "**/*schema*.json"
+        - "**/*schema*.yaml"
+    artifacts_required:
+      - "CONTRACT_REPORT.md"
+
+  # Benchmark - performance benchmarks (auto-skip if no perf-critical files changed)
+  benchmark:
+    skip_if:
+      no_files_match:
+        - "**/benchmark/**"
+        - "**/perf/**"
+        - "**/*benchmark*"
+    artifacts_required:
+      - "BENCHMARK_REPORT.md"
+
+  # QA - quality checks
+  qa:
+    # Default timeout per command (seconds)
+    timeout: 300
+    commands:
+      - name: "Tests"
+        command: "echo 'Configure your test command in .galangal/config.yaml'"
+        # timeout: 3600
+
+  # Review - code review (AI-driven)
+  review:
+    pass_marker: "APPROVE"
+    fail_marker: "REQUEST_CHANGES"
+    artifact: "REVIEW_NOTES.md"
+
+# =============================================================================
+# AI Backend Configuration
+# =============================================================================
+
+ai:
+  default: claude
+
+  backends:
+    claude:
+      command: "claude"
+      args: ["--output-format", "stream-json", "--verbose", "--max-turns", "{{max_turns}}", "--permission-mode", "bypassPermissions"]
+      max_turns: 200
+
+# =============================================================================
+# Pull Request Configuration
+# =============================================================================
+
+pr:
+  codex_review: false      # Set to true to add @codex review to PR body
+  base_branch: main
+
+# =============================================================================
+# GitHub Integration
+# =============================================================================
+# Configure how galangal integrates with GitHub Issues.
+# Run 'galangal github setup' to create required labels.
+
+github:
+  # Label that marks issues for galangal to pick up
+  pickup_label: galangal
+
+  # Label added when galangal starts working on an issue
+  in_progress_label: in-progress
+
+  # Colors for labels (hex without #)
+  label_colors:
+    galangal: "7C3AED"       # Purple
+    in-progress: "FCD34D"    # Yellow
+
+  # Map GitHub labels to task types
+  # Add your custom labels here
+  label_mapping:
+    bug:
+      - bug
+      - bugfix
+    feature:
+      - enhancement
+      - feature
+    docs:
+      - documentation
+      - docs
+    refactor:
+      - refactor
+    chore:
+      - chore
+      - maintenance
+    hotfix:
+      - hotfix
+      - critical
+
+# =============================================================================
+# Prompt Context
+# =============================================================================
+# Add project-specific patterns and instructions here.
+# This context is added to ALL stage prompts.
+
+prompt_context: |
+  ## Project: {project_name}
+
+  Add your project-specific patterns, coding standards,
+  and instructions here.
+
+# Per-stage prompt additions
+stage_context:
+  DEV: |
+    # Add DEV-specific context here
+  TEST: |
+    # Add TEST-specific context here
+"""
+
+
+def generate_default_config(project_name: str = "My Project") -> str:
+    """Generate a default config.yaml content."""
+    return DEFAULT_CONFIG_YAML.format(project_name=project_name)

galangal/config/loader.py

@@ -0,0 +1,163 @@
+"""
+Configuration loading and management.
+"""
+
+from pathlib import Path
+
+import yaml
+from pydantic import ValidationError as PydanticValidationError
+
+from galangal.config.schema import GalangalConfig
+from galangal.exceptions import ConfigError
+
+# Global config cache
+_config: GalangalConfig | None = None
+_project_root: Path | None = None
+
+
+def reset_caches() -> None:
+    """Reset all global caches. Used between tests to ensure clean state."""
+    global _config, _project_root
+    _config = None
+    _project_root = None
+
+
+def find_project_root(start_path: Path | None = None) -> Path:
+    """
+    Find the project root by looking for .galangal/ directory.
+    Falls back to git root, then current directory.
+    """
+    if start_path is None:
+        start_path = Path.cwd()
+
+    current = start_path.resolve()
+
+    # Walk up looking for .galangal/
+    while current != current.parent:
+        if (current / ".galangal").is_dir():
+            return current
+        if (current / ".git").is_dir():
+            # Found git root, use this as fallback
+            return current
+        current = current.parent
+
+    # Fall back to start path
+    return start_path.resolve()
+
+
+def get_project_root() -> Path:
+    """Get the cached project root."""
+    global _project_root
+    if _project_root is None:
+        _project_root = find_project_root()
+    return _project_root
+
+
+def set_project_root(path: Path) -> None:
+    """Set the project root (for testing)."""
+    global _project_root, _config
+    _project_root = path.resolve()
+    _config = None  # Reset config cache
+
+
+def load_config(project_root: Path | None = None) -> GalangalConfig:
+    """
+    Load configuration from .galangal/config.yaml.
+
+    Returns default config if file doesn't exist.
+    Raises ConfigError if file exists but is invalid.
+    """
+    global _config, _project_root
+
+    if project_root is not None:
+        _project_root = project_root.resolve()
+    elif _project_root is None:
+        _project_root = find_project_root()
+
+    config_path = _project_root / ".galangal" / "config.yaml"
+
+    if not config_path.exists():
+        _config = GalangalConfig()
+        return _config
+
+    try:
+        data = yaml.safe_load(config_path.read_text()) or {}
+    except yaml.YAMLError as e:
+        raise ConfigError(f"Invalid YAML in {config_path}: {e}") from e
+
+    try:
+        _config = GalangalConfig.model_validate(data)
+        return _config
+    except PydanticValidationError as e:
+        raise ConfigError(f"Invalid configuration in {config_path}: {e}") from e
+
+
+def get_config() -> GalangalConfig:
+    """Get the cached configuration, loading if necessary."""
+    global _config
+    if _config is None:
+        _config = load_config()
+    return _config
+
+
+def get_tasks_dir() -> Path:
+    """Get the tasks directory path.
+
+    Always returns an absolute path inside the project root.
+    Validates that the configured tasks_dir doesn't escape the project root.
+    """
+    config = get_config()
+    project_root = get_project_root()
+    tasks_dir = (project_root / config.tasks_dir).resolve()
+
+    # Ensure tasks_dir is inside project root (prevent path traversal)
+    try:
+        tasks_dir.relative_to(project_root)
+    except ValueError:
+        # tasks_dir is outside project root - use default
+        tasks_dir = project_root / "galangal-tasks"
+
+    return tasks_dir
+
+
+def get_done_dir() -> Path:
+    """Get the done tasks directory path."""
+    return get_tasks_dir() / "done"
+
+
+def get_active_file() -> Path:
+    """Get the active task marker file path."""
+    return get_tasks_dir() / ".active"
+
+
+def get_prompts_dir() -> Path:
+    """Get the project prompts override directory."""
+    return get_project_root() / ".galangal" / "prompts"
+
+
+def is_initialized() -> bool:
+    """Check if galangal has been initialized in this project.
+
+    Returns:
+        True if .galangal/config.yaml exists.
+    """
+    config_path = get_project_root() / ".galangal" / "config.yaml"
+    return config_path.exists()
+
+
+def require_initialized() -> bool:
+    """Check if initialized and print error if not.
+
+    Use this at the start of commands that require initialization.
+
+    Returns:
+        True if initialized, False if not (error already printed).
+    """
+    if is_initialized():
+        return True
+
+    from galangal.ui.console import print_error, print_info
+
+    print_error("Galangal has not been initialized in this project.")
+    print_info("Run 'galangal init' first to set up your project.")
+    return False

galangal/config/schema.py

@@ -0,0 +1,330 @@
+"""
+Configuration schema using Pydantic models.
+"""
+
+from pydantic import BaseModel, Field
+
+
+class ProjectConfig(BaseModel):
+    """Project-level configuration."""
+
+    name: str = Field(default="My Project", description="Project name")
+    approver_name: str | None = Field(
+        default=None, description="Default approver name for plan approvals"
+    )
+
+
+class StageConfig(BaseModel):
+    """Stage execution configuration."""
+
+    skip: list[str] = Field(default_factory=list, description="Stages to always skip")
+    timeout: int = Field(default=14400, description="Stage timeout in seconds (default: 4 hours)")
+    max_retries: int = Field(default=5, description="Max retries per stage")
+
+
+class PreflightCheck(BaseModel):
+    """A single preflight check."""
+
+    name: str = Field(description="Check name for display")
+    command: str | list[str] | None = Field(
+        default=None,
+        description="Command to run. String uses shell, list runs directly (safer for paths with spaces).",
+    )
+    path_exists: str | None = Field(default=None, description="Path that must exist")
+    expect_empty: bool = Field(default=False, description="Pass if output is empty")
+    warn_only: bool = Field(default=False, description="Warn but don't fail the stage")
+
+
+class TestGateTest(BaseModel):
+    """A single test suite configuration for the test gate."""
+
+    name: str = Field(description="Name of the test suite for display")
+    command: str = Field(description="Command to run the test suite")
+    timeout: int = Field(default=300, description="Timeout in seconds (default: 5 minutes)")
+
+
+class TestGateConfig(BaseModel):
+    """Configuration for the TEST_GATE stage.
+
+    The TEST_GATE stage runs configured test suites and requires all to pass
+    before proceeding. This is a mechanical stage (no AI) that acts as a
+    quality gate.
+    """
+
+    enabled: bool = Field(default=False, description="Enable the test gate stage")
+    tests: list[TestGateTest] = Field(
+        default_factory=list, description="Test suites to run"
+    )
+    fail_fast: bool = Field(
+        default=True, description="Stop on first test failure instead of running all"
+    )
+
+
+class ValidationCommand(BaseModel):
+    """A validation command configuration.
+
+    Commands can be specified as a string (shell execution) or list (direct execution).
+    List form is preferred when using placeholders like {task_dir} as it handles
+    paths with spaces correctly.
+
+    Supported placeholders:
+    - {task_dir}: Path to the task directory (galangal-tasks/<task-name>)
+    - {project_root}: Path to the project root directory
+    - {base_branch}: Configured base branch (e.g., "main")
+
+    Examples:
+        # String form (uses shell, supports &&, |, etc.)
+        command: "pytest tests/ && ruff check src/"
+
+        # List form (no shell, handles spaces in paths)
+        command: ["pytest", "{task_dir}/tests"]
+    """
+
+    name: str = Field(description="Command name for display")
+    command: str | list[str] = Field(
+        description="Command to run. String uses shell, list runs directly (safer for paths with spaces).",
+    )
+    optional: bool = Field(default=False, description="Don't fail if this command fails")
+    allow_failure: bool = Field(default=False, description="Report but don't block on failure")
+    timeout: int | None = Field(
+        default=None, description="Command timeout in seconds (overrides stage default)"
+    )
+
+
+class SkipCondition(BaseModel):
+    """Condition for skipping a stage."""
+
+    no_files_match: str | list[str] | None = Field(
+        default=None,
+        description="Skip if no files match this glob pattern (or list of patterns)",
+    )
+
+
+class StageValidation(BaseModel):
+    """Validation configuration for a single stage."""
+
+    skip_if: SkipCondition | None = Field(default=None, description="Skip condition")
+    timeout: int = Field(
+        default=300, description="Default timeout in seconds for validation commands"
+    )
+    commands: list[ValidationCommand] = Field(default_factory=list, description="Commands to run")
+    checks: list[PreflightCheck] = Field(
+        default_factory=list, description="Preflight checks (for preflight stage)"
+    )
+    pass_marker: str | None = Field(
+        default=None, description="Text marker indicating pass (for AI stages)"
+    )
+    fail_marker: str | None = Field(
+        default=None, description="Text marker indicating failure (for AI stages)"
+    )
+    artifact: str | None = Field(default=None, description="Artifact file to check for markers")
+    artifacts_required: list[str] = Field(
+        default_factory=list, description="Required artifact files"
+    )
+
+
+class ValidationConfig(BaseModel):
+    """All stage validations."""
+
+    preflight: StageValidation = Field(default_factory=StageValidation)
+    migration: StageValidation = Field(default_factory=StageValidation)
+    test: StageValidation = Field(default_factory=StageValidation)
+    test_gate: StageValidation = Field(default_factory=StageValidation)
+    contract: StageValidation = Field(default_factory=StageValidation)
+    qa: StageValidation = Field(default_factory=StageValidation)
+    security: StageValidation = Field(default_factory=StageValidation)
+    review: StageValidation = Field(default_factory=StageValidation)
+    docs: StageValidation = Field(default_factory=StageValidation)
+
+
+class AIBackendConfig(BaseModel):
+    """Configuration for an AI backend."""
+
+    command: str = Field(description="Command to invoke the AI")
+    args: list[str] = Field(default_factory=list, description="Command arguments")
+    max_turns: int = Field(default=200, description="Maximum conversation turns")
+    read_only: bool = Field(
+        default=False,
+        description="Backend runs in read-only mode (cannot write files). "
+        "Artifacts will be written from structured output via post-processing.",
+    )
+
+
+class AIConfig(BaseModel):
+    """AI backend configuration."""
+
+    default: str = Field(default="claude", description="Default backend")
+    backends: dict[str, AIBackendConfig] = Field(
+        default_factory=lambda: {
+            "claude": AIBackendConfig(
+                command="claude",
+                args=[
+                    "--output-format",
+                    "stream-json",
+                    "--verbose",
+                    "--max-turns",
+                    "{max_turns}",
+                    "--permission-mode",
+                    "bypassPermissions",
+                ],
+                max_turns=200,
+            ),
+            "codex": AIBackendConfig(
+                command="codex",
+                args=[
+                    "exec",
+                    "--full-auto",
+                    "--output-schema",
+                    "{schema_file}",
+                    "-o",
+                    "{output_file}",
+                ],
+                max_turns=50,
+                read_only=True,
+            ),
+        }
+    )
+    stage_backends: dict[str, str] = Field(
+        default_factory=dict,
+        description="Per-stage backend overrides (e.g., {'REVIEW': 'codex'})",
+    )
+
+
+class DocsConfig(BaseModel):
+    """Documentation paths configuration."""
+
+    changelog_dir: str = Field(
+        default="docs/changelog",
+        description="Directory for changelog entries (organized by year/month)",
+    )
+    security_audit: str = Field(
+        default="docs/security",
+        description="Directory for security audit reports",
+    )
+    general: str = Field(
+        default="docs",
+        description="Directory for general documentation",
+    )
+    update_changelog: bool = Field(
+        default=True,
+        description="Whether to update the changelog during DOCS stage",
+    )
+    update_security_audit: bool = Field(
+        default=True,
+        description="Whether to create/update security audit reports during SECURITY stage",
+    )
+    update_general_docs: bool = Field(
+        default=True,
+        description="Whether to update general documentation during DOCS stage",
+    )
+
+
+class LoggingConfig(BaseModel):
+    """Structured logging configuration."""
+
+    enabled: bool = Field(default=False, description="Enable structured logging to file")
+    level: str = Field(default="info", description="Log level: debug, info, warning, error")
+    file: str | None = Field(
+        default=None,
+        description="Log file path (e.g., 'logs/galangal.jsonl'). If not set, logs only to console.",
+    )
+    json_format: bool = Field(
+        default=True, description="Output JSON format (False for pretty console format)"
+    )
+    console: bool = Field(default=False, description="Also output to console (stderr)")
+
+
+class PRConfig(BaseModel):
+    """Pull request configuration."""
+
+    codex_review: bool = Field(default=False, description="Add @codex review to PR body")
+    base_branch: str = Field(default="main", description="Base branch for PRs")
+
+
+class TaskTypeSettings(BaseModel):
+    """Settings specific to a task type."""
+
+    skip_discovery: bool = Field(
+        default=False,
+        description="Skip the discovery Q&A phase for this task type",
+    )
+
+
+class GitHubLabelMapping(BaseModel):
+    """Maps GitHub labels to task types."""
+
+    bug: list[str] = Field(
+        default_factory=lambda: ["bug", "bugfix"],
+        description="Labels that map to bug_fix task type",
+    )
+    feature: list[str] = Field(
+        default_factory=lambda: ["enhancement", "feature"],
+        description="Labels that map to feature task type",
+    )
+    docs: list[str] = Field(
+        default_factory=lambda: ["documentation", "docs"],
+        description="Labels that map to docs task type",
+    )
+    refactor: list[str] = Field(
+        default_factory=lambda: ["refactor"],
+        description="Labels that map to refactor task type",
+    )
+    chore: list[str] = Field(
+        default_factory=lambda: ["chore", "maintenance"],
+        description="Labels that map to chore task type",
+    )
+    hotfix: list[str] = Field(
+        default_factory=lambda: ["hotfix", "critical"],
+        description="Labels that map to hotfix task type",
+    )
+
+
+class GitHubConfig(BaseModel):
+    """GitHub integration configuration."""
+
+    pickup_label: str = Field(
+        default="galangal",
+        description="Label that marks issues for galangal to pick up",
+    )
+    in_progress_label: str = Field(
+        default="in-progress",
+        description="Label added when galangal starts working on an issue",
+    )
+    label_colors: dict[str, str] = Field(
+        default_factory=lambda: {
+            "galangal": "7C3AED",  # Purple
+            "in-progress": "FCD34D",  # Yellow
+        },
+        description="Hex colors for labels (without #)",
+    )
+    label_mapping: GitHubLabelMapping = Field(
+        default_factory=GitHubLabelMapping,
+        description="Maps GitHub labels to task types",
+    )
+
+
+class GalangalConfig(BaseModel):
+    """Root configuration model."""
+
+    project: ProjectConfig = Field(default_factory=ProjectConfig)
+    tasks_dir: str = Field(default="galangal-tasks", description="Task storage directory")
+    branch_pattern: str = Field(default="task/{task_name}", description="Git branch naming pattern")
+    stages: StageConfig = Field(default_factory=StageConfig)
+    test_gate: TestGateConfig = Field(
+        default_factory=TestGateConfig,
+        description="Test gate configuration - mechanical test verification stage",
+    )
+    validation: ValidationConfig = Field(default_factory=ValidationConfig)
+    ai: AIConfig = Field(default_factory=AIConfig)
+    pr: PRConfig = Field(default_factory=PRConfig)
+    docs: DocsConfig = Field(default_factory=DocsConfig)
+    logging: LoggingConfig = Field(default_factory=LoggingConfig)
+    github: GitHubConfig = Field(default_factory=GitHubConfig)
+    prompt_context: str = Field(default="", description="Global context added to all prompts")
+    stage_context: dict[str, str] = Field(
+        default_factory=dict, description="Per-stage prompt context"
+    )
+    task_type_settings: dict[str, TaskTypeSettings] = Field(
+        default_factory=dict,
+        description="Per-task-type settings (e.g., skip_discovery for bugfix tasks)",
+    )