diamond-dev 0.1.0__py3-none-any.whl

diamond_dev/__init__.py

@@ -0,0 +1 @@
+"""Diamond Dev application package."""

diamond_dev/acceptance.py

@@ -0,0 +1,79 @@
+"""Acceptance marker helpers for wiki comparison pages."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Sequence
+from typing import Final
+
+from diamond_dev.errors import MalformedAcceptanceError
+
+DEFAULT_ACCEPTANCE_AGENTS: Final = ("codex", "claude")
+ACCEPTANCE_CHECKBOX: Final = "- [ ] Accept: (codex/claude)"
+_ACCEPTANCE_LINE_PATTERN: Final = re.compile(r"^- \[[ xX]\] Accept:")
+
+
+def append_acceptance_checkbox(
+    markdown: str,
+    agent_names: Sequence[str] = DEFAULT_ACCEPTANCE_AGENTS,
+) -> str:
+    """Append the deterministic acceptance checkbox to markdown content."""
+    separator = "" if markdown.endswith("\n") else "\n"
+    return f"{markdown}{separator}{acceptance_checkbox(agent_names)}\n"
+
+
+def ensure_acceptance_checkbox(
+    markdown: str,
+    agent_names: Sequence[str] = DEFAULT_ACCEPTANCE_AGENTS,
+) -> str:
+    """Return markdown with exactly one valid acceptance marker."""
+    acceptance_lines = _acceptance_lines(markdown)
+    if acceptance_lines:
+        parse_acceptance(markdown, agent_names)
+        return markdown
+    return append_acceptance_checkbox(markdown, agent_names)
+
+
+def parse_acceptance(
+    markdown: str,
+    agent_names: Sequence[str] = DEFAULT_ACCEPTANCE_AGENTS,
+) -> str | None:
+    """Parse the comparison acceptance marker."""
+    allowed_agents = tuple(agent_names)
+    acceptance_lines = _acceptance_lines(markdown)
+    if not acceptance_lines:
+        return None
+    if len(acceptance_lines) > 1:
+        raise MalformedAcceptanceError("Comparison file has multiple accept markers")
+
+    line = acceptance_lines[0]
+    if line == acceptance_checkbox(allowed_agents):
+        return None
+    normalized_line = line.replace("[X]", "[x]", 1)
+    for agent_name in allowed_agents:
+        if normalized_line == accepted_line(agent_name):
+            return agent_name
+    raise MalformedAcceptanceError(f"Invalid acceptance marker: {line}")
+
+
+def acceptance_checkbox(agent_names: Sequence[str]) -> str:
+    """Return the unchecked acceptance marker for allowed agents."""
+    return f"- [ ] Accept: ({'/'.join(agent_names)})"
+
+
+def accepted_line(agent_name: str) -> str:
+    """Return the checked acceptance marker for one agent."""
+    return f"- [x] Accept: {agent_name}"
+
+
+def acceptance_wait_delays() -> tuple[int, ...]:
+    """Return acceptance polling waits in seconds."""
+    return (120, *(minutes * 60 for minutes in range(3, 13)))
+
+
+def _acceptance_lines(markdown: str) -> list[str]:
+    return [
+        stripped_line
+        for line in markdown.splitlines()
+        if _ACCEPTANCE_LINE_PATTERN.match(stripped_line := line.strip())
+    ]

diamond_dev/agents.py

@@ -0,0 +1,186 @@
+"""Built-in agent adapter registry for Diamond Dev."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+from diamond_dev.commands import (
+    build_claude_interactive_review_command,
+    build_claude_print_command,
+    build_coderabbit_review_command,
+    build_codex_command,
+    build_gemini_command,
+)
+from diamond_dev.errors import DiamondDevError
+
+type AgentCapability = Literal[
+    "implementation",
+    "comparison_judge",
+    "comparison_fixer",
+    "review_provider",
+    "review_judge",
+    "review_fixer",
+    "final_reviewer",
+]
+type PromptCommandBuilder = Callable[[Path, str, str | None], tuple[str, ...]]
+type ReviewCommandBuilder = Callable[[str, str | None], tuple[str, ...]]
+type InteractiveReviewCommandBuilder = Callable[[str, str | None], tuple[str, ...]]
+
+
+@dataclass(frozen=True, slots=True)
+class AgentAdapter:
+    """Command adapter and capability metadata for one built-in agent CLI."""
+
+    name: str
+    executable: str
+    capabilities: frozenset[AgentCapability]
+    build_prompt_command: PromptCommandBuilder | None = None
+    build_review_command: ReviewCommandBuilder | None = None
+    build_interactive_review_command: InteractiveReviewCommandBuilder | None = None
+
+    def has_capability(self, capability: AgentCapability) -> bool:
+        """Return whether this adapter can fill a workflow role."""
+        return capability in self.capabilities
+
+    def require_capability(self, capability: AgentCapability) -> None:
+        """Raise when this adapter cannot fill a workflow role."""
+        if not self.has_capability(capability):
+            raise DiamondDevError(
+                f"Agent adapter `{self.name}` does not support `{capability}`",
+            )
+
+    def prompt_command(
+        self,
+        repo_dir: Path,
+        prompt: str,
+        *,
+        model: str | None,
+        capability: AgentCapability,
+    ) -> tuple[str, ...]:
+        """Build a prompt-driven command for a capable adapter."""
+        self.require_capability(capability)
+        if self.build_prompt_command is None:
+            raise DiamondDevError(
+                f"Agent adapter `{self.name}` cannot build prompt commands",
+            )
+        return self.build_prompt_command(repo_dir, prompt, model)
+
+    def review_command(
+        self,
+        base_branch: str,
+        *,
+        model: str | None,
+    ) -> tuple[str, ...]:
+        """Build a review-provider command."""
+        self.require_capability("review_provider")
+        if self.build_review_command is None:
+            raise DiamondDevError(
+                f"Agent adapter `{self.name}` cannot build review commands",
+            )
+        return self.build_review_command(base_branch, model)
+
+    def interactive_review_command(
+        self,
+        pr_number: str,
+        *,
+        model: str | None,
+    ) -> tuple[str, ...]:
+        """Build an interactive final-review command."""
+        self.require_capability("final_reviewer")
+        if self.build_interactive_review_command is None:
+            raise DiamondDevError(
+                f"Agent adapter `{self.name}` cannot build interactive review commands",
+            )
+        return self.build_interactive_review_command(pr_number, model)
+
+
+def _codex_prompt_command(
+    repo_dir: Path,
+    prompt: str,
+    model: str | None,
+) -> tuple[str, ...]:
+    return build_codex_command(repo_dir, prompt, model=model)
+
+
+def _claude_prompt_command(
+    _repo_dir: Path,
+    prompt: str,
+    model: str | None,
+) -> tuple[str, ...]:
+    return build_claude_print_command(prompt, model=model)
+
+
+def _gemini_prompt_command(
+    _repo_dir: Path,
+    prompt: str,
+    model: str | None,
+) -> tuple[str, ...]:
+    return build_gemini_command(prompt, model=model)
+
+
+def _coderabbit_review_command(
+    base_branch: str,
+    _model: str | None,
+) -> tuple[str, ...]:
+    return build_coderabbit_review_command(base_branch)
+
+
+def _claude_interactive_review_command(
+    pr_number: str,
+    model: str | None,
+) -> tuple[str, ...]:
+    return build_claude_interactive_review_command(pr_number, model=model)
+
+
+_CODE_WRITER_CAPABILITIES: frozenset[AgentCapability] = frozenset(
+    {
+        "implementation",
+        "comparison_fixer",
+        "review_judge",
+        "review_fixer",
+    },
+)
+
+BUILTIN_AGENT_ADAPTERS: Mapping[str, AgentAdapter] = {
+    "codex": AgentAdapter(
+        name="codex",
+        executable="codex",
+        capabilities=_CODE_WRITER_CAPABILITIES,
+        build_prompt_command=_codex_prompt_command,
+    ),
+    "claude": AgentAdapter(
+        name="claude",
+        executable="claude",
+        capabilities=frozenset({*_CODE_WRITER_CAPABILITIES, "final_reviewer"}),
+        build_prompt_command=_claude_prompt_command,
+        build_interactive_review_command=_claude_interactive_review_command,
+    ),
+    "gemini": AgentAdapter(
+        name="gemini",
+        executable="gemini",
+        capabilities=frozenset({"comparison_judge"}),
+        build_prompt_command=_gemini_prompt_command,
+    ),
+    "coderabbit": AgentAdapter(
+        name="coderabbit",
+        executable="coderabbit",
+        capabilities=frozenset({"review_provider"}),
+        build_review_command=_coderabbit_review_command,
+    ),
+}
+
+
+def adapter_names() -> frozenset[str]:
+    """Return names of built-in adapters."""
+    return frozenset(BUILTIN_AGENT_ADAPTERS)
+
+
+def resolve_adapter(adapter_name: str) -> AgentAdapter:
+    """Return a built-in adapter by name."""
+    try:
+        return BUILTIN_AGENT_ADAPTERS[adapter_name]
+    except (KeyError,) as error:
+        raise DiamondDevError(f"Unknown agent adapter: {adapter_name}") from error

diamond_dev/commands.py

@@ -0,0 +1,294 @@
+"""External command and prompt construction."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True, slots=True)
+class ComparisonBranchContext:
+    """One implementation branch supplied to a comparison judge."""
+
+    agent_name: str
+    branch: str
+    repo_dir: Path
+
+
+@dataclass(frozen=True, slots=True)
+class ComparisonPromptContext:
+    """Context supplied to a comparison judge."""
+
+    base_branch: str
+    comparison_bundle_file_name: str
+    branches: Sequence[ComparisonBranchContext]
+
+
+def build_codex_command(
+    repo_dir: Path,
+    prompt: str,
+    *,
+    model: str | None = None,
+) -> tuple[str, ...]:
+    """Build a non-interactive Codex command with full edit permissions."""
+    command = [
+        "codex",
+        "exec",
+        "-C",
+        str(repo_dir),
+    ]
+    if model is not None:
+        command.extend(("-m", model))
+    command.extend(("--dangerously-bypass-approvals-and-sandbox", prompt))
+    return tuple(command)
+
+
+def build_claude_print_command(
+    prompt: str,
+    *,
+    model: str | None = None,
+) -> tuple[str, ...]:
+    """Build a non-interactive Claude command with bypass permissions."""
+    command = ["claude"]
+    if model is not None:
+        command.extend(("--model", model))
+    command.extend((
+        "-p",
+        "--permission-mode",
+        "bypassPermissions",
+        "--dangerously-skip-permissions",
+        prompt,
+    ))
+    return tuple(command)
+
+
+def build_gemini_command(prompt: str, *, model: str | None = None) -> tuple[str, ...]:
+    """Build a headless Gemini command."""
+    command = ["gemini"]
+    if model is not None:
+        command.extend(("-m", model))
+    command.extend(("-p", prompt, "--skip-trust", "-y"))
+    return tuple(command)
+
+
+def build_coderabbit_review_command(base_branch: str) -> tuple[str, ...]:
+    """Build a plain CodeRabbit review command."""
+    return ("coderabbit", "review", "--plain", "--base", base_branch)
+
+
+def build_uv_sync_command() -> tuple[str, ...]:
+    """Build a locked uv package install command."""
+    return ("uv", "sync", "--locked")
+
+
+def build_pnpm_install_command() -> tuple[str, ...]:
+    """Build a frozen pnpm package install command."""
+    return ("pnpm", "install", "--frozen-lockfile")
+
+
+def build_gh_pr_list_command(head_branch: str) -> tuple[str, ...]:
+    """Build a deterministic GitHub PR lookup command for a workflow branch."""
+    return (
+        "gh",
+        "pr",
+        "list",
+        "--head",
+        head_branch,
+        "--state",
+        "all",
+        "--json",
+        "number,state,url",
+        "--limit",
+        "1",
+    )
+
+
+def build_gh_pr_create_command(
+    *,
+    base_branch: str,
+    head_branch: str,
+    title: str,
+    body: str,
+) -> tuple[str, ...]:
+    """Build a deterministic GitHub PR creation command."""
+    return (
+        "gh",
+        "pr",
+        "create",
+        "--base",
+        base_branch,
+        "--head",
+        head_branch,
+        "--title",
+        title,
+        "--body",
+        body,
+    )
+
+
+def build_gh_pr_edit_body_command(*, pr_url: str, body: str) -> tuple[str, ...]:
+    """Build a deterministic GitHub PR body update command."""
+    return ("gh", "pr", "edit", pr_url, "--body", body)
+
+
+def build_claude_interactive_review_command(
+    pr_number: str,
+    *,
+    model: str | None = None,
+) -> tuple[str, ...]:
+    """Build the final interactive Claude PR review command."""
+    command = ["claude"]
+    if model is not None:
+        command.extend(("--model", model))
+    command.extend((
+        "--permission-mode",
+        "bypassPermissions",
+        "--dangerously-skip-permissions",
+        f"/review {pr_number}",
+    ))
+    return tuple(command)
+
+
+def initial_implementation_prompt(
+    plan_file_name: str,
+    configured_prompt: str | None = None,
+) -> str:
+    """Return the initial implementation prompt for Codex or Claude."""
+    return _prompt_with_required_context(
+        configured_prompt,
+        fallback_prompt="Read and implement the supplied plan.",
+        required_lines=(
+            f"- Plan file: `{plan_file_name}`",
+            "- Commit your changes on the current branch.",
+            "- Do not push; diamond-dev will push committed work.",
+        ),
+    )
+
+
+def comparison_implementation_prompt(
+    comparison_file_name: str,
+    configured_prompt: str | None = None,
+) -> str:
+    """Return the prompt for the opposite agent comparison implementation."""
+    return _prompt_with_required_context(
+        configured_prompt,
+        fallback_prompt="Implement the requested comparison follow-up changes.",
+        required_lines=(
+            f"- Comparison file: `{comparison_file_name}`",
+            "- Inspect the current branch first because this prompt may be rerun.",
+            "- Avoid duplicating work that is already applied.",
+            "- Commit your changes.",
+            "- Do not push; diamond-dev will push committed work.",
+        ),
+    )
+
+
+def review_judgment_prompt(
+    review_file_name: str,
+    review_judgments_file_name: str,
+    review_provider: str,
+    review_judge: str,
+    configured_prompt: str | None = None,
+) -> str:
+    """Return the prompt asking Codex to classify CodeRabbit findings."""
+    return _prompt_with_required_context(
+        configured_prompt,
+        fallback_prompt="Evaluate each CodeRabbit review item.",
+        required_lines=(
+            f"- Review file: `{review_file_name}`",
+            f"- Structured judgment sidecar: `{review_judgments_file_name}`",
+            "- Write valid JSON to the structured judgment sidecar with "
+            "`schema_version`, `review_file`, `review_provider`, "
+            "`review_judge`, and `findings`.",
+            f"- Use `review_provider`: `{review_provider}`.",
+            f"- Use `review_judge`: `{review_judge}`.",
+            "- Each finding must have `id`, `decision`, `confidence`, and "
+            "`rationale`.",
+            "- Allowed decisions are `fix`, `decline`, and `needs_input`.",
+            "- Judge each item as (A) should fix, (B) decline fix, or "
+            "(C) requirements ambiguous or input needed.",
+            "- Append your judgements to the review file without removing "
+            "existing content.",
+            "- Commit the updated review file and structured judgment sidecar.",
+            "- Do not push; diamond-dev will push committed work.",
+        ),
+    )
+
+
+def review_fix_prompt(
+    review_file_name: str,
+    review_judgments_file_name: str,
+    configured_prompt: str | None = None,
+) -> str:
+    """Return the prompt asking Codex to implement accepted review fixes."""
+    return _prompt_with_required_context(
+        configured_prompt,
+        fallback_prompt="Implement accepted CodeRabbit review fixes.",
+        required_lines=(
+            f"- Review file: `{review_file_name}`",
+            f"- Structured judgment sidecar: `{review_judgments_file_name}`",
+            "- If the structured judgment sidecar exists and is valid, implement "
+            "every finding with decision `fix`.",
+            "- If the sidecar is missing or invalid, fall back to legacy markdown "
+            "judgments and implement every review item judged as (A) should fix.",
+            "- Do not implement items judged as (B) decline fix.",
+            "- Do not implement findings with decision `decline` or `needs_input`.",
+            "- Leave items judged as (C) requirements ambiguous or input needed "
+            "unchanged.",
+            "- Inspect the current branch first because this prompt may be rerun.",
+            "- Avoid duplicating work that is already applied.",
+            "- Commit your changes.",
+            "- Do not push; diamond-dev will push committed work.",
+        ),
+    )
+
+
+def gemini_comparison_prompt(
+    configured_prompt: str | None,
+    context: ComparisonPromptContext,
+) -> str:
+    """Return the comparison judgment prompt with mandatory run context."""
+    return _prompt_with_required_context(
+        configured_prompt,
+        fallback_prompt=_fallback_prompt(),
+        required_lines=_comparison_required_lines(context),
+    )
+
+
+def _fallback_prompt() -> str:
+    return (
+        "Compare the implementation branches against the base branch. Evaluate "
+        "correctness, completeness, maintainability, tests, and risk. Recommend "
+        "one implementation as the base and describe any follow-up changes the "
+        "comparison fixer should apply."
+    )
+
+
+def _comparison_required_lines(
+    context: ComparisonPromptContext,
+) -> tuple[str, ...]:
+    branch_lines = tuple(
+        f"- {branch.agent_name} branch: `{branch.branch}` in `{branch.repo_dir}`"
+        for branch in context.branches
+    )
+    return (
+        f"- Base branch: `{context.base_branch}`",
+        f"- Comparison bundle: `{context.comparison_bundle_file_name}`",
+        "- Read the comparison bundle before judging branch quality.",
+        *branch_lines,
+        "- Write the final comparison to `comparison.md` in the current directory.",
+        "- Do not modify any implementation repository.",
+    )
+
+
+def _prompt_with_required_context(
+    configured_prompt: str | None,
+    *,
+    fallback_prompt: str,
+    required_lines: tuple[str, ...],
+) -> str:
+    stripped_prompt = configured_prompt.strip() if configured_prompt else ""
+    prompt = stripped_prompt or fallback_prompt
+    required_context = "\n".join(required_lines)
+    return f"{prompt}\n\nRequired context:\n{required_context}"