ctrlrelay 0.1.5__py3-none-any.whl

ctrlrelay/core/__init__.py

@@ -0,0 +1,54 @@
+"""Core functionality for ctrlrelay orchestrator."""
+
+from ctrlrelay.core.checkpoint import (
+    CheckpointError,
+    CheckpointState,
+    CheckpointStatus,
+    blocked,
+    done,
+    failed,
+    read_checkpoint,
+)
+from ctrlrelay.core.config import (
+    Config,
+    ConfigError,
+    RepoConfig,
+    load_config,
+)
+from ctrlrelay.core.dispatcher import (
+    AgentAdapter,
+    ClaudeDispatcher,
+    SessionResult,
+    make_agent_dispatcher,
+)
+from ctrlrelay.core.github import GitHubCLI
+from ctrlrelay.core.poller import IssuePoller
+from ctrlrelay.core.pr_verifier import PRVerifier, VerificationResult
+from ctrlrelay.core.pr_watcher import PRWatcher
+from ctrlrelay.core.state import StateDB
+from ctrlrelay.core.worktree import WorktreeManager
+
+__all__ = [
+    "CheckpointError",
+    "CheckpointState",
+    "CheckpointStatus",
+    "AgentAdapter",
+    "ClaudeDispatcher",
+    "make_agent_dispatcher",
+    "Config",
+    "ConfigError",
+    "GitHubCLI",
+    "IssuePoller",
+    "PRVerifier",
+    "PRWatcher",
+    "RepoConfig",
+    "SessionResult",
+    "StateDB",
+    "VerificationResult",
+    "WorktreeManager",
+    "blocked",
+    "done",
+    "failed",
+    "load_config",
+    "read_checkpoint",
+]

ctrlrelay/core/audit.py

@@ -0,0 +1,257 @@
+"""Skill audit functionality for orchestrator readiness checks."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+
+import yaml
+
+
+class AuditCheck(str, Enum):
+    """Types of orchestrator readiness checks."""
+
+    CHECKPOINT = "checkpoint"
+    HEADLESS = "headless"
+    CONTEXT_PATH = "context_path"
+    ATTRIBUTION = "attribution"
+
+
+@dataclass
+class AuditResult:
+    """Result of a single audit check."""
+
+    passed: bool
+    reason: str = ""
+    auto_fixable: bool = False
+
+
+@dataclass
+class SkillAudit:
+    """Audit results for a single skill."""
+
+    name: str
+    path: Path
+    results: dict[AuditCheck, AuditResult] = field(default_factory=dict)
+
+    @property
+    def passed(self) -> bool:
+        """True if all checks passed."""
+        return all(r.passed for r in self.results.values())
+
+    @property
+    def status(self) -> str:
+        """Human-readable status."""
+        return "READY" if self.passed else "NOT READY"
+
+
+@dataclass
+class SkillInfo:
+    """Basic skill information from SKILL.md."""
+
+    name: str
+    path: Path
+    content: str
+    frontmatter: dict
+
+
+# Patterns for headless check
+INTERACTIVE_PATTERNS = [
+    r"\binput\s*\(",
+    r"\bread\s+-p\b",
+    r"Confirm\s*\(",
+    r"typer\.confirm\s*\(",
+]
+
+BROWSER_ONLY_TOOLS = [
+    "mcp__playwright__",
+    "mcp__chrome_devtools__",
+]
+
+# Patterns for checkpoint check
+CHECKPOINT_PATTERNS = [
+    r"from\s+ctrlrelay\s+import\s+checkpoint",
+    r"from\s+ctrlrelay\.core\.checkpoint\s+import",
+    r"checkpoint\.(done|blocked|failed)\s*\(",
+    r"CTRLRELAY_STATE_FILE",
+]
+
+# Attribution patterns to avoid in output
+ATTRIBUTION_PATTERNS = [
+    r"\bClaude\b",
+    r"\bAnthropic\b",
+    r"Generated by AI",
+    r"AI Assistant",
+]
+
+
+def run_check(skill: SkillInfo, check: AuditCheck) -> AuditResult:
+    """Run a single audit check on a skill."""
+    content = skill.content
+    tools = skill.frontmatter.get("tools", "")
+
+    if check == AuditCheck.CHECKPOINT:
+        for pattern in CHECKPOINT_PATTERNS:
+            if re.search(pattern, content):
+                return AuditResult(passed=True)
+        return AuditResult(passed=False, reason="No checkpoint protocol usage found")
+
+    if check == AuditCheck.HEADLESS:
+        for pattern in INTERACTIVE_PATTERNS:
+            if re.search(pattern, content):
+                reason = f"Interactive prompt pattern found: {pattern}"
+                return AuditResult(passed=False, reason=reason)
+        for tool in BROWSER_ONLY_TOOLS:
+            if tool in content or tool in tools:
+                if "fallback" not in content.lower() and "cli" not in content.lower():
+                    reason = f"Browser-only tool without fallback: {tool}"
+                    return AuditResult(passed=False, reason=reason)
+        return AuditResult(passed=True)
+
+    if check == AuditCheck.CONTEXT_PATH:
+        if "REPO_CONTEXT_PATH" in content or "$REPO_CONTEXT_PATH" in content:
+            return AuditResult(passed=True)
+        if "context" in content.lower() and "/" in content:
+            return AuditResult(
+                passed=False, reason="May use hardcoded context path", auto_fixable=True
+            )
+        return AuditResult(passed=True)
+
+    if check == AuditCheck.ATTRIBUTION:
+        for pattern in ATTRIBUTION_PATTERNS:
+            match = re.search(pattern, content, re.IGNORECASE)
+            if match:
+                reason = f"Attribution pattern found: {match.group()}"
+                return AuditResult(passed=False, reason=reason, auto_fixable=True)
+        return AuditResult(passed=True)
+
+    return AuditResult(passed=True)
+
+
+def discover_skills(skills_dir: Path) -> list[SkillInfo]:
+    """Discover all skills in a directory.
+
+    Args:
+        skills_dir: Path to skills directory.
+
+    Returns:
+        List of SkillInfo for each skill found.
+    """
+    skills = []
+
+    if not skills_dir.exists():
+        return skills
+
+    for skill_md in skills_dir.glob("*/SKILL.md"):
+        content = skill_md.read_text()
+
+        # Parse YAML frontmatter
+        frontmatter = {}
+        match = re.match(r"^---\n(.*?)\n---", content, re.DOTALL)
+        if match:
+            try:
+                frontmatter = yaml.safe_load(match.group(1)) or {}
+            except yaml.YAMLError:
+                pass
+
+        name = frontmatter.get("name", skill_md.parent.name)
+        skills.append(
+            SkillInfo(
+                name=name,
+                path=skill_md.parent,
+                content=content,
+                frontmatter=frontmatter,
+            )
+        )
+
+    return sorted(skills, key=lambda s: s.name)
+
+
+def audit_skill(skill: SkillInfo) -> SkillAudit:
+    """Run all audit checks on a skill.
+
+    Args:
+        skill: Skill information.
+
+    Returns:
+        SkillAudit with all check results.
+    """
+    results = {}
+    for check in AuditCheck:
+        results[check] = run_check(skill, check)
+
+    return SkillAudit(
+        name=skill.name,
+        path=skill.path,
+        results=results,
+    )
+
+
+def audit_all(skills_dir: Path) -> list[SkillAudit]:
+    """Audit all skills in a directory.
+
+    Args:
+        skills_dir: Path to skills directory.
+
+    Returns:
+        List of SkillAudit results.
+    """
+    skills = discover_skills(skills_dir)
+    return [audit_skill(skill) for skill in skills]
+
+
+def format_report(audits: list[SkillAudit]) -> str:
+    """Format audit results as markdown report.
+
+    Args:
+        audits: List of skill audit results.
+
+    Returns:
+        Markdown formatted report.
+    """
+    lines = [
+        "## Skill Audit Report",
+        "",
+        "| Skill | Checkpoint | Headless | Context | Attribution | Status |",
+        "|-------|------------|----------|---------|-------------|--------|",
+    ]
+
+    for audit in audits:
+        def icon(check: AuditCheck) -> str:
+            result = audit.results.get(check)
+            if result is None:
+                return "➖"
+            return "✅" if result.passed else "❌"
+
+        lines.append(
+            f"| {audit.name} "
+            f"| {icon(AuditCheck.CHECKPOINT)} "
+            f"| {icon(AuditCheck.HEADLESS)} "
+            f"| {icon(AuditCheck.CONTEXT_PATH)} "
+            f"| {icon(AuditCheck.ATTRIBUTION)} "
+            f"| {audit.status} |"
+        )
+
+    # Summary
+    ready = sum(1 for a in audits if a.passed)
+    total = len(audits)
+    lines.extend([
+        "",
+        f"**Summary:** {ready}/{total} skills ready for orchestrator",
+    ])
+
+    # Details for failed checks
+    failed_audits = [a for a in audits if not a.passed]
+    if failed_audits:
+        lines.extend(["", "### Issues", ""])
+        for audit in failed_audits:
+            lines.append(f"**{audit.name}:**")
+            for check, result in audit.results.items():
+                if not result.passed:
+                    fixable = " (auto-fixable)" if result.auto_fixable else ""
+                    lines.append(f"- {check.value}: {result.reason}{fixable}")
+            lines.append("")
+
+    return "\n".join(lines)

ctrlrelay/core/checkpoint.py

@@ -0,0 +1,155 @@
+"""Checkpoint protocol for skill-orchestrator communication."""
+
+from __future__ import annotations
+
+import json
+import os
+from datetime import datetime, timezone
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, Field, model_validator
+
+
+class CheckpointStatus(str, Enum):
+    """Status values for checkpoint state."""
+
+    DONE = "DONE"
+    BLOCKED_NEEDS_INPUT = "BLOCKED_NEEDS_INPUT"
+    FAILED = "FAILED"
+
+
+class CheckpointState(BaseModel):
+    """State written by skills to communicate with orchestrator."""
+
+    version: str = "1"
+    status: CheckpointStatus
+    session_id: str
+    timestamp: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+
+    summary: str | None = None
+
+    question: str | None = None
+    question_context: dict[str, Any] | None = None
+
+    error: str | None = None
+    recoverable: bool = True
+
+    outputs: dict[str, Any] = Field(default_factory=dict)
+
+    @model_validator(mode="after")
+    def validate_status_fields(self) -> "CheckpointState":
+        """Validate that status-dependent fields are present."""
+        if self.status == CheckpointStatus.BLOCKED_NEEDS_INPUT and not self.question:
+            raise ValueError("question is required when status is BLOCKED_NEEDS_INPUT")
+        if self.status == CheckpointStatus.FAILED and not self.error:
+            raise ValueError("error is required when status is FAILED")
+        return self
+
+
+class CheckpointError(Exception):
+    """Raised when checkpoint operations fail."""
+
+
+def _get_state_file() -> Path:
+    """Get state file path from environment."""
+    path = os.environ.get("CTRLRELAY_STATE_FILE")
+    if not path:
+        raise CheckpointError("CTRLRELAY_STATE_FILE environment variable not set")
+    return Path(path)
+
+
+def _get_session_id() -> str:
+    """Get session ID from environment."""
+    session_id = os.environ.get("CTRLRELAY_SESSION_ID")
+    if not session_id:
+        raise CheckpointError("CTRLRELAY_SESSION_ID environment variable not set")
+    return session_id
+
+
+def _write_checkpoint(state: CheckpointState) -> None:
+    """Write checkpoint state atomically."""
+    state_file = _get_state_file()
+    temp_file = state_file.with_suffix(".json.tmp")
+
+    state_file.parent.mkdir(parents=True, exist_ok=True)
+
+    # Write to temp file first
+    temp_file.write_text(state.model_dump_json(indent=2))
+
+    # Atomic rename
+    temp_file.rename(state_file)
+
+
+def done(summary: str, outputs: dict[str, Any] | None = None) -> None:
+    """Report successful completion."""
+    # Check state file first so error message is consistent
+    _get_state_file()
+    state = CheckpointState(
+        status=CheckpointStatus.DONE,
+        session_id=_get_session_id(),
+        summary=summary,
+        outputs=outputs or {},
+    )
+    _write_checkpoint(state)
+
+
+def blocked(question: str, context: dict[str, Any] | None = None) -> None:
+    """Report blocked on human input."""
+    # Check state file first so error message is consistent
+    _get_state_file()
+    state = CheckpointState(
+        status=CheckpointStatus.BLOCKED_NEEDS_INPUT,
+        session_id=_get_session_id(),
+        question=question,
+        question_context=context,
+    )
+    _write_checkpoint(state)
+
+
+def failed(error: str, recoverable: bool = True) -> None:
+    """Report failure."""
+    # Check state file first so error message is consistent
+    _get_state_file()
+    state = CheckpointState(
+        status=CheckpointStatus.FAILED,
+        session_id=_get_session_id(),
+        error=error,
+        recoverable=recoverable,
+    )
+    _write_checkpoint(state)
+
+
+def read_checkpoint(path: Path, delete_after: bool = False) -> CheckpointState:
+    """Read and parse a checkpoint file.
+
+    Used by the orchestrator to read skill results.
+
+    Args:
+        path: Path to the checkpoint file.
+        delete_after: If True, delete the file after reading.
+
+    Returns:
+        Parsed CheckpointState.
+
+    Raises:
+        CheckpointError: If file not found or invalid.
+    """
+    if not path.exists():
+        raise CheckpointError(f"Checkpoint file not found: {path}")
+
+    try:
+        data = json.loads(path.read_text())
+    except json.JSONDecodeError as e:
+        raise CheckpointError(f"Failed to parse checkpoint file: {e}") from e
+
+    try:
+        state = CheckpointState.model_validate(data)
+    except Exception as e:
+        raise CheckpointError(f"Invalid checkpoint data: {e}") from e
+
+    if delete_after:
+        path.unlink()
+
+    return state