ctrlrelay 0.1.5__py3-none-any.whl

ctrlrelay/core/config.py

@@ -0,0 +1,291 @@
+"""Configuration loading and validation for ctrlrelay."""
+
+from __future__ import annotations
+
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+import yaml
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+
+class ConfigError(Exception):
+    """Raised when configuration loading or validation fails."""
+
+
+class TransportType(str, Enum):
+    TELEGRAM = "telegram"
+    FILE_MOCK = "file_mock"
+
+
+class AutomationPolicy(str, Enum):
+    AUTO = "auto"
+    ASK = "ask"
+    NEVER = "never"
+
+
+class PathsConfig(BaseModel):
+    """File system paths configuration."""
+
+    state_db: Path
+    worktrees: Path
+    bare_repos: Path
+    contexts: Path
+    skills: Path
+
+    @field_validator("*", mode="before")
+    @classmethod
+    def expand_path(cls, v: Any) -> Any:
+        if isinstance(v, str):
+            return Path(v).expanduser()
+        return v
+
+
+class AgentConfig(BaseModel):
+    """Headless coding-agent configuration.
+
+    ``type`` selects which adapter the dispatcher uses to talk to the
+    agent CLI. Today only ``claude`` is implemented; the field exists
+    so future adapters (e.g. ``codex``, ``opencode``, ``hermes``) can
+    be plugged in without a config schema change. The other fields
+    (``binary``, ``default_timeout_seconds``, ``output_format``) are
+    common across most CLI-driven agents; adapters that need agent-
+    specific knobs can add a nested sub-model later.
+    """
+
+    type: str = "claude"
+    binary: str = "claude"
+    default_timeout_seconds: int = 1800
+    output_format: str = "json"
+
+
+# Backwards-compat alias. Older code and docs reference ``ClaudeConfig``;
+# keep the name importable but have it resolve to the renamed class so
+# `isinstance(cfg, ClaudeConfig)` and `ClaudeConfig(...)` still work.
+# Scheduled for removal once downstream repos migrate.
+ClaudeConfig = AgentConfig
+
+
+class TelegramConfig(BaseModel):
+    """Telegram transport configuration."""
+
+    bot_token_env: str = "CTRLRELAY_TELEGRAM_TOKEN"
+    chat_id: int = 0
+    socket_path: Path = Field(
+        default_factory=lambda: Path("~/.ctrlrelay/ctrlrelay.sock").expanduser()
+    )
+
+    @field_validator("socket_path", mode="before")
+    @classmethod
+    def expand_socket_path(cls, v: Any) -> Any:
+        if isinstance(v, str):
+            return Path(v).expanduser()
+        return v
+
+
+class FileMockConfig(BaseModel):
+    """File mock transport configuration for testing."""
+
+    inbox: Path
+    outbox: Path
+
+    @field_validator("*", mode="before")
+    @classmethod
+    def expand_path(cls, v: Any) -> Any:
+        if isinstance(v, str):
+            return Path(v).expanduser()
+        return v
+
+
+class TransportConfig(BaseModel):
+    """Transport configuration (Telegram or file mock)."""
+
+    type: TransportType = TransportType.FILE_MOCK
+    telegram: TelegramConfig | None = None
+    file_mock: FileMockConfig | None = None
+
+    @model_validator(mode="after")
+    def validate_transport_config(self) -> "TransportConfig":
+        if self.type == TransportType.TELEGRAM and self.telegram is None:
+            raise ValueError("telegram config required when type is 'telegram'")
+        if self.type == TransportType.FILE_MOCK and self.file_mock is None:
+            raise ValueError("file_mock config required when type is 'file_mock'")
+        return self
+
+
+class DashboardConfig(BaseModel):
+    """Dashboard client configuration."""
+
+    enabled: bool = True
+    url: str = ""
+    auth_token_env: str = "CTRLRELAY_DASHBOARD_TOKEN"
+    sync_config_on_heartbeat: bool = False
+
+
+class DeployConfig(BaseModel):
+    """Deployment configuration for a repo."""
+
+    provider: str = "digitalocean"
+    app_id: str = ""
+
+
+class CodeReviewConfig(BaseModel):
+    """Code review configuration for a repo."""
+
+    method: str = "mcp_then_cli"
+    mcp_tool: str = "mcp__codex-reviewer__codex_review"
+    cli_command: str = "codex review"
+
+
+class AutomationConfig(BaseModel):
+    """Automation policies for a repo."""
+
+    dependabot_patch: AutomationPolicy = AutomationPolicy.AUTO
+    dependabot_minor: AutomationPolicy = AutomationPolicy.ASK
+    dependabot_major: AutomationPolicy = AutomationPolicy.NEVER
+    codeql_dismiss: AutomationPolicy = AutomationPolicy.ASK
+    secret_alerts: AutomationPolicy = AutomationPolicy.NEVER
+    deploy_after_merge: AutomationPolicy = AutomationPolicy.AUTO
+
+
+class RepoConfig(BaseModel):
+    """Configuration for a single repository."""
+
+    name: str
+    local_path: Path
+    automation: AutomationConfig = Field(default_factory=AutomationConfig)
+    deploy: DeployConfig | None = None
+    code_review: CodeReviewConfig = Field(default_factory=CodeReviewConfig)
+    dev_branch_template: str = "fix/issue-{n}"
+
+    @field_validator("local_path", mode="before")
+    @classmethod
+    def expand_local_path(cls, v: Any) -> Any:
+        if isinstance(v, str):
+            return Path(v).expanduser()
+        return v
+
+
+class SchedulesConfig(BaseModel):
+    """Cron schedules for background jobs run by the poller daemon.
+
+    Values are standard 5-field cron expressions (minute hour dom month dow),
+    evaluated in the top-level ``timezone``. Each schedule is validated at
+    config load time so an unparseable expression fails fast rather than
+    silently disabling the job.
+    """
+
+    secops_cron: str = "0 6 * * *"
+
+    @field_validator("secops_cron")
+    @classmethod
+    def validate_cron(cls, v: str) -> str:
+        from ctrlrelay.core.scheduler import _build_vixie_trigger
+
+        try:
+            # Build through the same helper the scheduler uses so
+            # (a) DOW normalization and (b) Vixie DOM/DOW-OR splitting
+            # are both exercised at load time. Bad expressions surface
+            # synchronously instead of at daemon start.
+            _build_vixie_trigger(v, timezone=None)
+        except Exception as e:
+            raise ValueError(
+                f"invalid cron expression {v!r}: {e}"
+            ) from e
+        return v
+
+
+class Config(BaseModel):
+    """Root configuration model for ctrlrelay orchestrator."""
+
+    version: str = "1"
+    node_id: str
+    timezone: str = "UTC"
+    paths: PathsConfig
+    agent: AgentConfig = Field(default_factory=AgentConfig)
+    transport: TransportConfig
+    dashboard: DashboardConfig = Field(default_factory=DashboardConfig)
+    schedules: SchedulesConfig = Field(default_factory=SchedulesConfig)
+    repos: list[RepoConfig] = Field(default_factory=list)
+
+    @model_validator(mode="before")
+    @classmethod
+    def migrate_claude_to_agent(cls, data: Any) -> Any:
+        """Accept the legacy ``claude:`` top-level key as an alias for
+        ``agent:``. Emits a ``DeprecationWarning`` so operators see the
+        migration hint in logs. Removed in a future release.
+
+        If both keys are present, ``agent`` wins and ``claude`` is
+        ignored (fail-loud would break supervised daemons; we prefer
+        silent win-on-new-name during the migration window)."""
+        if isinstance(data, dict) and "claude" in data and "agent" not in data:
+            import warnings
+            warnings.warn(
+                "config key 'claude:' is deprecated; rename to 'agent:'. "
+                "See https://github.com/AInvirion/ctrlrelay/blob/main/"
+                "CHANGELOG.md for the migration.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            data["agent"] = data.pop("claude")
+        return data
+
+    @property
+    def claude(self) -> AgentConfig:
+        """Legacy attribute alias so callers still writing
+        ``config.claude.binary`` keep working. New code should prefer
+        ``config.agent.*``."""
+        return self.agent
+
+    @field_validator("timezone")
+    @classmethod
+    def validate_timezone(cls, v: str) -> str:
+        """Reject unparseable IANA zones at load time.
+
+        Since the scheduler feeds ``timezone`` directly into APScheduler's
+        CronTrigger, a typo like ``America/Santiagoo`` would only surface
+        as a ``ZoneInfoNotFoundError`` when the poller daemon starts —
+        much worse than a synchronous config error at load.
+        """
+        from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+        try:
+            ZoneInfo(v)
+        except ZoneInfoNotFoundError as e:
+            raise ValueError(f"unknown timezone {v!r}: {e}") from e
+        return v
+
+
+def load_config(path: Path | str) -> Config:
+    """Load and validate configuration from a YAML file.
+
+    Args:
+        path: Path to the orchestrator.yaml file.
+
+    Returns:
+        Validated Config object.
+
+    Raises:
+        ConfigError: If the file cannot be loaded or validation fails.
+    """
+    path = Path(path)
+
+    if not path.exists():
+        raise ConfigError(f"Config file not found: {path}")
+
+    try:
+        with open(path) as f:
+            data = yaml.safe_load(f)
+    except OSError as e:
+        raise ConfigError(f"Failed to read config file: {e}") from e
+    except yaml.YAMLError as e:
+        raise ConfigError(f"Failed to parse YAML: {e}") from e
+
+    if data is None:
+        raise ConfigError("Config file is empty")
+
+    try:
+        return Config.model_validate(data)
+    except Exception as e:
+        raise ConfigError(f"Config validation failed: {e}") from e

ctrlrelay/core/dispatcher.py

@@ -0,0 +1,202 @@
+"""Headless coding-agent subprocess dispatcher for ctrlrelay.
+
+Today the only concrete adapter is :class:`ClaudeDispatcher` (wraps
+``claude -p``). The :func:`make_agent_dispatcher` factory is the seam
+where additional backends (Codex, OpenCode, Hermes, Kiro, …) will plug
+in: each adapter must expose the same async ``spawn_session`` shape
+so pipelines can stay agent-agnostic.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import shutil
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Protocol
+
+from ctrlrelay.core.checkpoint import CheckpointState, CheckpointStatus, read_checkpoint
+
+if TYPE_CHECKING:
+    from ctrlrelay.core.config import AgentConfig
+
+
+def _find_claude() -> str:
+    """Find claude binary, checking common paths if not in PATH."""
+    claude = shutil.which("claude")
+    if claude:
+        return claude
+    for path in [
+        os.path.expanduser("~/.local/bin/claude"),
+        "/usr/local/bin/claude",
+        "/opt/homebrew/bin/claude",
+    ]:
+        if os.path.isfile(path) and os.access(path, os.X_OK):
+            return path
+    return "claude"
+
+
+@dataclass
+class SessionResult:
+    """Result of a Claude session."""
+
+    session_id: str
+    exit_code: int
+    state: CheckpointState | None
+    stdout: str = ""
+    stderr: str = ""
+
+    @property
+    def success(self) -> bool:
+        return self.state is not None and self.state.status == CheckpointStatus.DONE
+
+    @property
+    def blocked(self) -> bool:
+        return (
+            self.state is not None
+            and self.state.status == CheckpointStatus.BLOCKED_NEEDS_INPUT
+        )
+
+    @property
+    def failed(self) -> bool:
+        return self.state is None or self.state.status == CheckpointStatus.FAILED
+
+
+@dataclass
+class ClaudeDispatcher:
+    """Spawns and manages Claude subprocess sessions."""
+
+    claude_binary: str = field(default_factory=_find_claude)
+    default_timeout: int = 1800
+    extra_env: dict[str, str] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        # Only auto-resolve the bare default. Absolute paths, relative paths
+        # (resolved vs. working_dir by the child), and custom bare names pass
+        # through so explicit config is never silently overridden.
+        if self.claude_binary == "claude":
+            resolved = shutil.which("claude")
+            self.claude_binary = resolved or _find_claude()
+
+    async def spawn_session(
+        self,
+        session_id: str,
+        prompt: str,
+        working_dir: Path,
+        state_file: Path,
+        timeout: int | None = None,
+        resume_session_id: str | None = None,
+    ) -> SessionResult:
+        """Spawn a Claude session and wait for completion."""
+        timeout = timeout or self.default_timeout
+
+        env = os.environ.copy()
+        env.update(self.extra_env)
+        env["CTRLRELAY_SESSION_ID"] = session_id
+        env["CTRLRELAY_STATE_FILE"] = str(state_file)
+
+        cmd = [
+            self.claude_binary,
+            "-p", prompt,
+            "--output-format", "json",
+            "--dangerously-skip-permissions",
+        ]
+        if resume_session_id:
+            cmd.extend(["--resume", resume_session_id])
+
+        proc = await asyncio.create_subprocess_exec(
+            *cmd,
+            cwd=working_dir,
+            env=env,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+
+        try:
+            stdout, stderr = await asyncio.wait_for(
+                proc.communicate(), timeout=timeout
+            )
+        except asyncio.TimeoutError:
+            proc.kill()
+            await proc.wait()
+            return SessionResult(
+                session_id=session_id,
+                exit_code=-1,
+                state=None,
+                stderr="Session timed out",
+            )
+        except asyncio.CancelledError:
+            # Scheduler/shutdown cancel: kill the child BEFORE re-raising
+            # so `claude` isn't left running against the worktree after
+            # the daemon exits. Shield the wait so further cancels don't
+            # orphan the process between `kill()` and the reaping.
+            if proc.returncode is None:
+                proc.kill()
+                try:
+                    await asyncio.shield(proc.wait())
+                except asyncio.CancelledError:
+                    pass
+            raise
+
+        state = None
+        if state_file.exists():
+            try:
+                state = read_checkpoint(state_file, delete_after=True)
+            except Exception:
+                pass
+
+        return SessionResult(
+            session_id=session_id,
+            exit_code=proc.returncode or 0,
+            state=state,
+            stdout=stdout.decode(),
+            stderr=stderr.decode(),
+        )
+
+
+class AgentAdapter(Protocol):
+    """Protocol every coding-agent adapter must satisfy.
+
+    An adapter is a thin wrapper over an agent CLI that handles:
+    spawning the subprocess, passing the prompt and state-file path,
+    enforcing the timeout, and translating the checkpoint JSON the
+    agent writes into a :class:`SessionResult`.
+
+    Pipelines (dev, secops) only ever interact with this protocol —
+    they never import concrete adapters — so adding a new backend
+    means implementing this and registering it in
+    :func:`make_agent_dispatcher`.
+    """
+
+    async def spawn_session(
+        self,
+        session_id: str,
+        prompt: str,
+        working_dir: Path,
+        state_file: Path,
+        timeout: int | None = None,
+        resume_session_id: str | None = None,
+    ) -> SessionResult:
+        ...
+
+
+def make_agent_dispatcher(agent_config: "AgentConfig") -> AgentAdapter:
+    """Build an adapter for the configured ``agent.type``.
+
+    Raises :class:`NotImplementedError` with a clear error message if
+    the configured type has no adapter — makes a typo surface loudly
+    at daemon startup instead of silently falling back to Claude.
+    """
+    t = agent_config.type
+    if t == "claude":
+        return ClaudeDispatcher(
+            claude_binary=agent_config.binary,
+            default_timeout=agent_config.default_timeout_seconds,
+        )
+    raise NotImplementedError(
+        f"agent.type={t!r} has no adapter yet. Implement one that "
+        "satisfies the AgentAdapter protocol in "
+        "src/ctrlrelay/core/dispatcher.py and register it here, then "
+        "open a PR. Supported today: 'claude'."
+    )