devflow-toolkit 0.3.0__py3-none-any.whl

devflow/adapters/__init__.py

@@ -0,0 +1,47 @@
+"""Agent harness adapters."""
+
+from devflow.adapters.agents import AgentsFileWriter
+from devflow.adapters.base import (
+  AdapterError,
+  FileChange,
+  HarnessAdapter,
+  HarnessExecutionError,
+  Invocation,
+  InvocationResult,
+  RunContext,
+  SetupContext,
+  SetupResult,
+  execute_invocation,
+)
+from devflow.adapters.detector import (
+  DetectedHarness,
+  HarnessSelection,
+  detect_harnesses,
+  select_harness,
+)
+from devflow.adapters.registry import (
+  adapter_names,
+  adapters,
+  get_adapter,
+)
+
+__all__ = [
+  "AdapterError",
+  "AgentsFileWriter",
+  "DetectedHarness",
+  "FileChange",
+  "HarnessAdapter",
+  "HarnessExecutionError",
+  "HarnessSelection",
+  "Invocation",
+  "InvocationResult",
+  "RunContext",
+  "SetupContext",
+  "SetupResult",
+  "adapter_names",
+  "adapters",
+  "detect_harnesses",
+  "execute_invocation",
+  "get_adapter",
+  "select_harness",
+]

devflow/adapters/agents.py

@@ -0,0 +1,49 @@
+"""Generate the generic AGENTS.md fallback entry point."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from devflow.adapters.instructions import (
+  MANAGED_MARKER as _MANAGED_MARKER,
+  render_agent_instructions,
+  write_text_managed,
+)
+from devflow.core.config import DevFlowConfig
+from devflow.models.profile import Profile
+from devflow.models.project import Project
+
+MANAGED_MARKER = _MANAGED_MARKER
+
+
+@dataclass(frozen=True)
+class AgentsWriteResult:
+  """Outcome of writing the AGENTS.md file."""
+
+  path: Path
+  status: str
+
+
+class AgentsFileWriter:
+  """Create or update the managed AGENTS.md entry point."""
+
+  def render(
+    self,
+    project: Project,
+    profiles: list[Profile],
+    constitution_files: list[str],
+    config: DevFlowConfig,
+  ) -> str:
+    """Render the agent instructions for a project."""
+    return render_agent_instructions(
+      project=project,
+      profiles=profiles,
+      constitution_files=constitution_files,
+      config=config,
+    )
+
+  def write(self, root: Path, content: str) -> AgentsWriteResult:
+    """Write AGENTS.md without overwriting unmanaged user content."""
+    result = write_text_managed(root / "AGENTS.md", content, root=root)
+    return AgentsWriteResult(path=result.path, status=result.status)

devflow/adapters/base.py

@@ -0,0 +1,81 @@
+"""Infrastructure for provider-independent agent harness adapters."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+
+from devflow.core.ports import (
+  AdapterError,
+  FileChange,
+  HarnessExecutionError,
+  HarnessPort,
+  Invocation,
+  InvocationResult,
+  RunContext,
+  SetupContext,
+  SetupResult,
+)
+
+__all__ = [
+  "AdapterError",
+  "FileChange",
+  "HarnessAdapter",
+  "HarnessExecutionError",
+  "HarnessPort",
+  "Invocation",
+  "InvocationResult",
+  "RunContext",
+  "SetupContext",
+  "SetupResult",
+  "execute_invocation",
+]
+
+
+class HarnessAdapter(HarnessPort):
+  """Base class for adapters whose harness is an executable on PATH."""
+
+  executable: str
+
+  def is_available(self) -> bool:
+    """Return whether the harness executable is on PATH."""
+    return shutil.which(self.executable) is not None
+
+
+def execute_invocation(invocation: Invocation) -> InvocationResult:
+  """Run a harness while preserving terminal access in interactive mode."""
+  environment = os.environ.copy()
+  # ``cwd=`` changes the process directory but does not update PWD.
+  # Harnesses such as OpenCode resolve the project from PWD and would
+  # otherwise load the agents of the directory where DevFlow was called.
+  environment["PWD"] = str(invocation.cwd)
+  kwargs: dict[str, object] = {
+    "cwd": str(invocation.cwd),
+    "env": environment,
+    "text": True,
+    "check": False,
+  }
+  if invocation.stdin_text is not None:
+    kwargs["input"] = invocation.stdin_text
+  if not invocation.interactive:
+    kwargs["capture_output"] = True
+
+  try:
+    completed = subprocess.run(  # noqa: S603
+      list(invocation.argv),
+      **kwargs,
+    )
+  except OSError as error:
+    msg = (
+      f"Could not start '{invocation.argv[0]}': {error.strerror}. "
+      "Check that the harness is installed and on PATH."
+    )
+    raise HarnessExecutionError(msg) from error
+
+  return InvocationResult(
+    returncode=completed.returncode,
+    stdout=completed.stdout or "",
+    stderr=completed.stderr or "",
+    output_path=invocation.output_path,
+  )

devflow/adapters/claude_code.py

@@ -0,0 +1,120 @@
+"""Claude Code harness adapter."""
+
+from __future__ import annotations
+
+import json
+
+from devflow.adapters.base import (
+  FileChange,
+  HarnessAdapter,
+  Invocation,
+  RunContext,
+  SetupContext,
+  SetupResult,
+)
+from devflow.adapters.instructions import (
+  render_agent_instructions,
+  write_text_managed,
+)
+
+
+class ClaudeCodeAdapter(HarnessAdapter):
+  """Generate CLAUDE.md and invoke Claude Code with scoped permissions."""
+
+  name = "claude-code"
+  display_name = "Claude Code"
+  executable = "claude"
+
+  def setup(self, context: SetupContext) -> SetupResult:
+    content = render_agent_instructions(
+      project=context.project,
+      profiles=list(context.profiles),
+      constitution_files=list(context.constitution_files),
+      config=context.config,
+      imports=True,
+    )
+    result = write_text_managed(
+      context.root / "CLAUDE.md",
+      content,
+      root=context.root,
+    )
+    return SetupResult(
+      changes=(FileChange(path=result.path, status=result.status),)
+    )
+
+  def build_run(self, context: RunContext) -> Invocation:
+    settings = json.dumps(
+      {"permissions": self._permission_rules(context)},
+      separators=(",", ":"),
+    )
+    root = context.root
+
+    if context.mode == "interactive":
+      argv = (
+        self.executable,
+        "--permission-mode",
+        "dontAsk",
+        "--settings",
+        settings,
+        context.prompt,
+      )
+      return Invocation(argv=argv, cwd=root, interactive=True)
+
+    tools = self._read_tools(context)
+    if context.permissions.allow_source_code_changes:
+      tools.extend(["Edit", "Write", "Bash"])
+    argv = (
+      self.executable,
+      "-p",
+      "--output-format",
+      "text",
+      "--permission-mode",
+      "dontAsk",
+      "--tools",
+      ",".join(tools),
+      "--settings",
+      settings,
+      context.prompt,
+    )
+    return Invocation(argv=argv, cwd=root, interactive=False)
+
+  def permission_warnings(
+    self,
+    context: RunContext,
+  ) -> tuple[str, ...]:
+    warnings: list[str] = []
+    if context.mode == "non-interactive" and (
+      context.permissions.allow_source_code_changes
+    ):
+      warnings.append(
+        "Claude Code runs with edit and shell tools because source code "
+        "changes are allowed. The specification prompt still forbids "
+        "implementing the change."
+      )
+    return tuple(warnings)
+
+  def _read_tools(self, context: RunContext) -> list[str]:
+    if not context.permissions.allow_project_read:
+      return []
+    return ["Read", "Grep", "Glob"]
+
+  def _permission_rules(
+    self,
+    context: RunContext,
+  ) -> dict[str, list[str]]:
+    allow: list[str] = []
+    deny: list[str] = []
+
+    if context.permissions.allow_project_read:
+      allow.extend(["Read", "Grep", "Glob"])
+
+    if context.permissions.allow_source_code_changes:
+      allow.extend(["Edit", "Bash"])
+    elif context.permissions.allow_spec_write:
+      allow.append("Edit(.devflow/specs/**)")
+
+    deny.extend(["WebFetch", "WebSearch", "Task"])
+    if not context.permissions.allow_source_code_changes:
+      deny.extend(["Bash", "NotebookEdit"])
+
+    return {"allow": allow, "deny": deny}

devflow/adapters/codex.py

@@ -0,0 +1,111 @@
+"""Codex CLI harness adapter."""
+
+from __future__ import annotations
+
+from devflow.adapters.base import (
+  FileChange,
+  HarnessAdapter,
+  Invocation,
+  RunContext,
+  SetupContext,
+  SetupResult,
+)
+from devflow.adapters.instructions import (
+  render_agent_instructions,
+  write_text_managed,
+)
+
+
+class CodexAdapter(HarnessAdapter):
+  """Generate AGENTS.md and invoke Codex in exec or interactive mode."""
+
+  name = "codex"
+  display_name = "Codex"
+  executable = "codex"
+
+  def setup(self, context: SetupContext) -> SetupResult:
+    content = render_agent_instructions(
+      project=context.project,
+      profiles=list(context.profiles),
+      constitution_files=list(context.constitution_files),
+      config=context.config,
+    )
+    result = write_text_managed(
+      context.root / "AGENTS.md",
+      content,
+      root=context.root,
+    )
+    return SetupResult(
+      changes=(FileChange(path=result.path, status=result.status),)
+    )
+
+  def build_run(self, context: RunContext) -> Invocation:
+    root = context.root
+    if context.mode == "interactive":
+      sandbox = (
+        "workspace-write"
+        if context.permissions.allow_spec_write
+        or context.permissions.allow_source_code_changes
+        else "read-only"
+      )
+      argv = (
+        self.executable,
+        "--sandbox",
+        sandbox,
+        "--ask-for-approval",
+        "on-request",
+        "-C",
+        str(root),
+        context.prompt,
+      )
+      return Invocation(argv=argv, cwd=root, interactive=True)
+
+    sandbox = (
+      "workspace-write"
+      if context.permissions.allow_source_code_changes
+      else "read-only"
+    )
+    argv = [
+      self.executable,
+      "exec",
+      "--sandbox",
+      sandbox,
+      "--skip-git-repo-check",
+      "-C",
+      str(root),
+    ]
+    if context.output_path is not None:
+      argv.extend(["-o", str(context.output_path)])
+    argv.append("-")
+    return Invocation(
+      argv=tuple(argv),
+      cwd=root,
+      interactive=False,
+      stdin_text=context.prompt,
+      output_path=context.output_path,
+    )
+
+  def permission_warnings(
+    self,
+    context: RunContext,
+  ) -> tuple[str, ...]:
+    warnings: list[str] = []
+    if context.mode == "interactive":
+      if not context.permissions.allow_source_code_changes:
+        warnings.append(
+          "Codex sandboxes writes to the workspace but cannot limit them "
+          "to .devflow/specs; command approvals remain the technical "
+          "gate. Review any write outside the specs directory."
+        )
+      if not context.permissions.allow_spec_write:
+        warnings.append(
+          "Specification writes are disabled for Codex. The specification "
+          "will fall back to deterministic DevFlow output."
+        )
+    elif context.permissions.allow_source_code_changes:
+      warnings.append(
+        "Codex runs with workspace-write because source code changes are "
+        "allowed. The specification prompt still forbids implementing "
+        "the change."
+      )
+    return tuple(warnings)

devflow/adapters/detector.py

@@ -0,0 +1,118 @@
+"""Detection and selection of installed agent harnesses."""
+
+from __future__ import annotations
+
+import shutil
+import sys
+from dataclasses import dataclass, field
+from typing import Callable, Sequence
+
+from devflow.adapters.registry import adapters
+from devflow.core.config import canonical_harness_name
+
+
+@dataclass(frozen=True)
+class DetectedHarness:
+  """An installed harness executable."""
+
+  name: str
+  executable: str
+  path: str
+
+
+@dataclass(frozen=True)
+class HarnessSelection:
+  """Result of resolving the configured harness."""
+
+  harness: str | None
+  warnings: tuple[str, ...] = field(default_factory=tuple)
+  candidates: tuple[str, ...] = ()
+
+
+def detect_harnesses(
+  which: Callable[[str], str | None] = shutil.which,
+) -> tuple[DetectedHarness, ...]:
+  """Return the harnesses whose executables are available on PATH."""
+  detected: list[DetectedHarness] = []
+  for adapter in adapters():
+    executable = which(adapter.executable)
+    if executable:
+      detected.append(
+        DetectedHarness(
+          name=adapter.name,
+          executable=adapter.executable,
+          path=executable,
+        )
+      )
+  return tuple(detected)
+
+
+def select_harness(
+  requested: str,
+  detected: Sequence[DetectedHarness],
+  prompt: Callable[[list[str]], str | None] | None = None,
+) -> HarnessSelection:
+  """Resolve ``auto`` or a concrete harness without choosing arbitrarily."""
+  canonical = canonical_harness_name(requested)
+  names = tuple(harness.name for harness in detected)
+
+  if canonical == "none":
+    return HarnessSelection(harness=None, candidates=names)
+  if canonical != "auto":
+    if canonical in names:
+      return HarnessSelection(harness=canonical, candidates=names)
+    return HarnessSelection(
+      harness=None,
+      warnings=(
+        f"Agent harness '{canonical}' is not installed or not on PATH. "
+        "DevFlow will use deterministic static analysis.",
+      ),
+      candidates=names,
+    )
+
+  if not names:
+    return HarnessSelection(
+      harness=None,
+      warnings=(
+        "No supported agent harness was found on PATH. DevFlow will use "
+        "deterministic static analysis.",
+      ),
+      candidates=names,
+    )
+  if len(names) == 1:
+    return HarnessSelection(harness=names[0], candidates=names)
+
+  if prompt is None or not sys.stdin.isatty():
+    return HarnessSelection(
+      harness=None,
+      warnings=(
+        "Multiple agent harnesses are installed ("
+        + ", ".join(names)
+        + "). No harness was selected because DevFlow is not running in "
+        "an interactive terminal. Set agent.harness in "
+        ".devflow/config.yaml or pass --harness.",
+      ),
+      candidates=names,
+    )
+
+  chosen = prompt(list(names))
+  if chosen is None:
+    return HarnessSelection(
+      harness=None,
+      warnings=(
+        "No agent harness was selected. DevFlow will use deterministic "
+        "static analysis.",
+      ),
+      candidates=names,
+    )
+  chosen_name = canonical_harness_name(chosen)
+  if chosen_name not in names:
+    return HarnessSelection(
+      harness=None,
+      warnings=(
+        f"Unknown harness selection: {chosen}. DevFlow will use "
+        "deterministic static analysis.",
+      ),
+      candidates=names,
+    )
+  return HarnessSelection(harness=chosen_name, candidates=names)