devflow-toolkit 0.3.0__py3-none-any.whl

devflow/adapters/instructions.py

@@ -0,0 +1,263 @@
+"""Shared rendering and safe writing of harness integration files."""
+
+from __future__ import annotations
+
+import json
+import os
+import stat
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from devflow.core.config import DevFlowConfig
+from devflow.models.profile import Profile
+from devflow.models.project import Project
+
+MANAGED_MARKER = "<!-- devflow:managed -->"
+
+
+class ManagedWriteError(OSError):
+  """Raised when a managed integration file would escape the project."""
+
+
+@dataclass(frozen=True)
+class ManagedWriteResult:
+  """Outcome of writing a managed integration file."""
+
+  path: Path
+  status: str
+
+
+def _managed_path(root: Path, path: Path) -> Path:
+  """Resolve a managed file path, rejecting symlinks and escapes."""
+  if path.is_symlink():
+    msg = f"Managed file is a symbolic link: {path}"
+    raise ManagedWriteError(msg)
+
+  resolved_root = root.resolve()
+  target = path.resolve()
+  try:
+    target.relative_to(resolved_root)
+  except ValueError as error:
+    msg = (
+      "Managed file must stay inside the project root: "
+      f"{path}"
+    )
+    raise ManagedWriteError(msg) from error
+  return target
+
+
+def _write_atomic(path: Path, content: str) -> None:
+  """Write text atomically inside an already validated directory."""
+  descriptor, temporary_name = tempfile.mkstemp(
+    prefix=f".{path.name}-",
+    suffix=".tmp",
+    dir=path.parent,
+  )
+  temporary = Path(temporary_name)
+  try:
+    with os.fdopen(
+      descriptor,
+      "w",
+      encoding="utf-8",
+      newline="\n",
+    ) as handle:
+      handle.write(content)
+      handle.flush()
+      os.fsync(handle.fileno())
+
+    mode = 0o644
+    try:
+      mode = stat.S_IMODE(path.stat().st_mode)
+    except OSError:
+      pass
+    os.chmod(temporary, mode)
+    temporary.replace(path)
+  finally:
+    temporary.unlink(missing_ok=True)
+
+
+def render_agent_instructions(
+  project: Project,
+  profiles: list[Profile],
+  constitution_files: list[str],
+  config: DevFlowConfig,
+  *,
+  imports: bool = False,
+) -> str:
+  """Render the shared, harness-independent project instructions."""
+  detected_profiles = [
+    profile for profile in profiles if profile.name != "base"
+  ]
+  lines = [
+    MANAGED_MARKER,
+    "# DevFlow Agent Instructions",
+    "",
+    "You are working on an existing software project.",
+    "",
+    "Before analyzing, planning or implementing any change:",
+    "",
+  ]
+
+  if imports:
+    lines.extend(
+      [
+        "The following constitution documents are imported into this "
+        "context:",
+        "",
+      ]
+    )
+    for filename in constitution_files:
+      lines.append(f"@.devflow/constitution/{filename}")
+  else:
+    for index, filename in enumerate(constitution_files, start=1):
+      lines.append(
+        f"{index}. Read `.devflow/constitution/{filename}`."
+      )
+
+  lines.extend(
+    [
+      "",
+      "Only apply technology-specific guidelines when the "
+      "corresponding technology is present in the project.",
+      "",
+      "## Project Context",
+      "",
+      f"- Project: `{project.name}`",
+      f"- Type: `{project.project_type}`",
+      "- Profiles: "
+      + (
+        ", ".join(
+          f"`{profile.name}`" for profile in detected_profiles
+        )
+        or "base only"
+      ),
+      "- Languages: "
+      + (", ".join(project.languages) or "not detected"),
+      "- Frameworks: "
+      + (", ".join(project.frameworks) or "not detected"),
+      "",
+      "## Existing Codebase",
+      "",
+      "- Inspect the relevant existing code before making changes.",
+      "- Understand current implementations and dependencies.",
+      "- Reuse existing patterns and components when appropriate.",
+      "- Do not assume the project is a greenfield application.",
+      "",
+      "## Specification Workflow",
+      "",
+      "When creating a specification:",
+      "",
+      "- Analyze the relevant existing implementation.",
+      "- Identify affected components.",
+      "- Define expected behavior.",
+      "- Document functional requirements.",
+      "- Define verifiable acceptance criteria.",
+      "- Identify constraints and unresolved questions.",
+      "- Do not implement code during specification generation.",
+      "- Write specifications only under the configured specs "
+      "directory.",
+      "",
+      "## Configuration",
+      "",
+      f"- Configuration: `{config.path.relative_to(config.root)}`",
+      "- Specifications: "
+      f"`{config.specifications_path.relative_to(config.root)}`",
+      "- Plans: "
+      f"`{config.plans_path.relative_to(config.root)}`",
+      "",
+      "Always respect the project constitution.",
+      "",
+    ]
+  )
+  return "\n".join(lines)
+
+
+def write_text_managed(
+  path: Path,
+  content: str,
+  *,
+  root: Path,
+  marker: str = MANAGED_MARKER,
+) -> ManagedWriteResult:
+  """Create or update a text file without overwriting unmanaged content."""
+  if path.is_symlink():
+    return ManagedWriteResult(path=path, status="skipped")
+
+  target = _managed_path(root, path)
+  target.parent.mkdir(parents=True, exist_ok=True)
+  target = _managed_path(root, target)
+
+  if target.exists():
+    try:
+      existing = target.read_text(encoding="utf-8")
+    except OSError:
+      return ManagedWriteResult(path=target, status="skipped")
+
+    if marker not in existing:
+      return ManagedWriteResult(path=target, status="skipped")
+    if existing == content:
+      return ManagedWriteResult(path=target, status="unchanged")
+
+    _write_atomic(target, content)
+    return ManagedWriteResult(path=target, status="updated")
+
+  _write_atomic(target, content)
+  return ManagedWriteResult(path=target, status="created")
+
+
+def write_json_managed(
+  path: Path,
+  data: dict[str, Any],
+  *,
+  root: Path,
+  marker_key: str = "devflowManaged",
+) -> ManagedWriteResult:
+  """Create or update a JSON file marked as DevFlow-managed."""
+  payload = {marker_key: True, **data}
+  content = json.dumps(payload, indent=2) + "\n"
+
+  if path.is_symlink():
+    return ManagedWriteResult(path=path, status="skipped")
+
+  target = _managed_path(root, path)
+  target.parent.mkdir(parents=True, exist_ok=True)
+  target = _managed_path(root, target)
+
+  if target.exists():
+    try:
+      existing = json.loads(target.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+      return ManagedWriteResult(path=target, status="skipped")
+
+    if not isinstance(existing, dict) or not existing.get(marker_key):
+      return ManagedWriteResult(path=target, status="skipped")
+    if existing == payload:
+      return ManagedWriteResult(path=target, status="unchanged")
+
+    _write_atomic(target, content)
+    return ManagedWriteResult(path=target, status="updated")
+
+  _write_atomic(target, content)
+  return ManagedWriteResult(path=target, status="created")
+
+
+def write_json_if_missing(
+  path: Path,
+  data: dict[str, Any],
+  *,
+  root: Path,
+) -> ManagedWriteResult:
+  """Create a JSON configuration file only when it does not exist."""
+  if path.is_symlink():
+    return ManagedWriteResult(path=path, status="skipped")
+
+  target = _managed_path(root, path)
+  if target.exists():
+    return ManagedWriteResult(path=target, status="unchanged")
+
+  target.parent.mkdir(parents=True, exist_ok=True)
+  target = _managed_path(root, target)
+  _write_atomic(target, json.dumps(data, indent=2) + "\n")
+  return ManagedWriteResult(path=target, status="created")

devflow/adapters/kiro.py

@@ -0,0 +1,211 @@
+"""Kiro CLI harness adapter."""
+
+from __future__ import annotations
+
+from devflow.adapters.base import (
+  FileChange,
+  HarnessAdapter,
+  Invocation,
+  RunContext,
+  SetupContext,
+  SetupResult,
+)
+from devflow.adapters.instructions import (
+  MANAGED_MARKER,
+  render_agent_instructions,
+  write_json_managed,
+  write_text_managed,
+)
+
+INTERACTIVE_AGENT = "devflow-spec"
+READONLY_AGENT = "devflow-spec-readonly"
+
+
+class KiroAdapter(HarnessAdapter):
+  """Generate native Kiro steering files and custom agents."""
+
+  name = "kiro"
+  display_name = "Kiro"
+  executable = "kiro-cli"
+
+  def setup(self, context: SetupContext) -> SetupResult:
+    changes: list[FileChange] = []
+    warnings: list[str] = []
+
+    steering = context.root / ".kiro" / "steering"
+    for document in context.constitution.documents:
+      content = self._render_steering(document.name, document.content)
+      result = write_text_managed(
+        steering / f"devflow-{document.name}",
+        content,
+        root=context.root,
+      )
+      changes.append(FileChange(path=result.path, status=result.status))
+      if result.status == "skipped":
+        warnings.append(
+          f"Kiro steering file {result.path.relative_to(context.root)} "
+          "contains unmanaged content and was left untouched."
+        )
+
+    workflow = render_agent_instructions(
+      project=context.project,
+      profiles=list(context.profiles),
+      constitution_files=list(context.constitution_files),
+      config=context.config,
+    )
+    workflow_result = write_text_managed(
+      steering / "devflow-spec-workflow.md",
+      workflow,
+      root=context.root,
+    )
+    changes.append(
+      FileChange(
+        path=workflow_result.path,
+        status=workflow_result.status,
+      )
+    )
+
+    agents = context.root / ".kiro" / "agents"
+    interactive = write_json_managed(
+      agents / f"{INTERACTIVE_AGENT}.json",
+      self._interactive_agent(context),
+      root=context.root,
+    )
+    changes.append(
+      FileChange(path=interactive.path, status=interactive.status)
+    )
+    if interactive.status == "skipped":
+      warnings.append(
+        "Existing .kiro/agents/devflow-spec.json is unmanaged and was "
+        "left untouched."
+      )
+
+    readonly = write_json_managed(
+      agents / f"{READONLY_AGENT}.json",
+      self._readonly_agent(),
+      root=context.root,
+    )
+    changes.append(
+      FileChange(path=readonly.path, status=readonly.status)
+    )
+    if readonly.status == "skipped":
+      warnings.append(
+        "Existing .kiro/agents/devflow-spec-readonly.json is unmanaged "
+        "and was left untouched."
+      )
+
+    return SetupResult(changes=tuple(changes), warnings=tuple(warnings))
+
+  def build_run(self, context: RunContext) -> Invocation:
+    root = context.root
+    if context.mode == "interactive":
+      writable = (
+        context.permissions.allow_spec_write
+        or context.permissions.allow_source_code_changes
+      )
+      agent = INTERACTIVE_AGENT if writable else READONLY_AGENT
+      trusted = "fs_read"
+      if context.permissions.allow_source_code_changes:
+        trusted = "fs_read,fs_write"
+      argv = (
+        self.executable,
+        "chat",
+        "--agent",
+        agent,
+        f"--trust-tools={trusted}",
+        context.prompt,
+      )
+      return Invocation(argv=argv, cwd=root, interactive=True)
+
+    argv = (
+      self.executable,
+      "chat",
+      "--no-interactive",
+      "--agent",
+      READONLY_AGENT,
+      "--trust-tools=fs_read",
+      "--output-format",
+      "text",
+      context.prompt,
+    )
+    return Invocation(argv=argv, cwd=root, interactive=False)
+
+  def permission_warnings(
+    self,
+    context: RunContext,
+  ) -> tuple[str, ...]:
+    warnings: list[str] = []
+    if context.mode == "interactive":
+      if context.permissions.allow_source_code_changes:
+        warnings.append(
+          "Kiro is trusted to write with fs_write because source code "
+          "changes are allowed. The specification prompt still forbids "
+          "implementing the change."
+        )
+      elif context.permissions.allow_spec_write:
+        warnings.append(
+          "Kiro custom agents can restrict tools but cannot scope "
+          "fs_write to .devflow/specs. Writes require explicit approval; "
+          "reject any write outside the specs directory."
+        )
+    return tuple(warnings)
+
+  def _render_steering(self, name: str, content: str) -> str:
+    lines = [
+      "---",
+      "inclusion: always",
+      "---",
+      MANAGED_MARKER,
+      f"# DevFlow Constitution: {name}",
+      "",
+      f"Source: `.devflow/constitution/{name}`",
+      "",
+      content.rstrip(),
+      "",
+    ]
+    return "\n".join(lines)
+
+  def _interactive_agent(
+    self,
+    context: SetupContext,
+  ) -> dict[str, object]:
+    tools = ["read", "grep", "glob"]
+    allowed = ["read", "grep", "glob"]
+    if context.permissions.allow_spec_write:
+      tools.append("write")
+    if context.permissions.allow_source_code_changes:
+      tools.append("shell")
+      allowed.append("write")
+      allowed.append("shell")
+
+    return {
+      "name": INTERACTIVE_AGENT,
+      "description": (
+        "DevFlow specification agent. Reads the project, asks "
+        "clarifying questions and writes only DevFlow specifications."
+      ),
+      "prompt": (
+        "Follow the DevFlow steering files. Generate the requested "
+        "specification under .devflow/specs and do not modify "
+        "application source code."
+      ),
+      "tools": tools,
+      "allowedTools": allowed,
+      "includeMcpJson": False,
+    }
+
+  def _readonly_agent(self) -> dict[str, object]:
+    return {
+      "name": READONLY_AGENT,
+      "description": (
+        "Read-only DevFlow specification agent. Returns a complete "
+        "specification without modifying the project."
+      ),
+      "prompt": (
+        "Follow the DevFlow steering files. Return a complete "
+        "specification as the final answer without writing any file."
+      ),
+      "tools": ["read", "grep", "glob"],
+      "allowedTools": ["read", "grep", "glob"],
+      "includeMcpJson": False,
+    }

devflow/adapters/opencode.py

@@ -0,0 +1,237 @@
+"""OpenCode harness adapter."""
+
+from __future__ import annotations
+
+import yaml
+
+from devflow.adapters.base import (
+  FileChange,
+  HarnessAdapter,
+  Invocation,
+  RunContext,
+  SetupContext,
+  SetupResult,
+)
+from devflow.adapters.instructions import (
+  MANAGED_MARKER,
+  render_agent_instructions,
+  write_json_if_missing,
+  write_text_managed,
+)
+
+INTERACTIVE_AGENT = "devflow-spec"
+READONLY_AGENT = "devflow-spec-readonly"
+
+
+class OpenCodeAdapter(HarnessAdapter):
+  """Generate OpenCode agents and invoke mini or run mode."""
+
+  name = "opencode"
+  display_name = "OpenCode"
+  executable = "opencode"
+
+  def setup(self, context: SetupContext) -> SetupResult:
+    changes: list[FileChange] = []
+    warnings: list[str] = []
+
+    instructions = 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",
+      instructions,
+      root=context.root,
+    )
+    changes.append(FileChange(path=result.path, status=result.status))
+
+    config_result = write_json_if_missing(
+      context.root / "opencode.json",
+      {"$schema": "https://opencode.ai/config.json"},
+      root=context.root,
+    )
+    changes.append(
+      FileChange(path=config_result.path, status=config_result.status)
+    )
+
+    agents_directory = context.root / ".opencode" / "agents"
+    interactive = write_text_managed(
+      agents_directory / f"{INTERACTIVE_AGENT}.md",
+      self._render_agent(
+        name=INTERACTIVE_AGENT,
+        description=(
+          "DevFlow specification agent. Reads the project, asks "
+          "clarifying questions and writes only DevFlow specs."
+        ),
+        context=context,
+        interactive=True,
+      ),
+      root=context.root,
+    )
+    changes.append(
+      FileChange(path=interactive.path, status=interactive.status)
+    )
+
+    readonly = write_text_managed(
+      agents_directory / f"{READONLY_AGENT}.md",
+      self._render_agent(
+        name=READONLY_AGENT,
+        description=(
+          "Read-only DevFlow specification agent. Returns a complete "
+          "specification without modifying the project."
+        ),
+        context=context,
+        interactive=False,
+      ),
+      root=context.root,
+    )
+    changes.append(
+      FileChange(path=readonly.path, status=readonly.status)
+    )
+
+    if result.status == "skipped":
+      warnings.append(
+        "AGENTS.md contains unmanaged content and was left untouched."
+      )
+    return SetupResult(changes=tuple(changes), warnings=tuple(warnings))
+
+  def build_run(self, context: RunContext) -> Invocation:
+    root = context.root
+    if context.mode == "interactive":
+      argv = (
+        self.executable,
+        "mini",
+        "--agent",
+        INTERACTIVE_AGENT,
+        "--prompt",
+        context.prompt,
+      )
+      return Invocation(argv=argv, cwd=root, interactive=True)
+
+    agent = (
+      INTERACTIVE_AGENT
+      if context.permissions.allow_source_code_changes
+      else READONLY_AGENT
+    )
+    argv = (
+      self.executable,
+      "run",
+      "--agent",
+      agent,
+      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(
+        "OpenCode runs with an agent that may edit source code because "
+        "source changes are allowed. The specification prompt still "
+        "forbids implementing the change."
+      )
+    if not context.permissions.allow_project_read:
+      warnings.append(
+        "Project reads are disabled; OpenCode cannot inspect the "
+        "codebase. DevFlow will use deterministic analysis."
+      )
+    return tuple(warnings)
+
+  def _render_agent(
+    self,
+    *,
+    name: str,
+    description: str,
+    context: SetupContext,
+    interactive: bool,
+  ) -> str:
+    permissions = self._permissions(context, interactive=interactive)
+    frontmatter = yaml.safe_dump(
+      {
+        "description": description,
+        "mode": "primary",
+        "permissions": permissions,
+      },
+      sort_keys=False,
+      allow_unicode=True,
+    ).strip()
+    body = [
+      MANAGED_MARKER,
+      f"# {name}",
+      "",
+      "You are the DevFlow specification agent for this project.",
+      "",
+      "Follow `AGENTS.md` and the project constitution. Analyze the "
+      "existing code before writing.",
+      "",
+      "Write only under `.devflow/specs/`. Never modify application "
+      "source code while generating a specification.",
+      "",
+      "The complete task, target path and output contract are provided "
+      "in the user prompt for each run.",
+      "",
+    ]
+    return f"---\n{frontmatter}\n---\n\n" + "\n".join(body)
+
+  def _permissions(
+    self,
+    context: SetupContext,
+    *,
+    interactive: bool,
+  ) -> list[dict[str, str]]:
+    permissions: list[dict[str, str]] = []
+    if context.permissions.allow_project_read:
+      for action in ("read", "glob", "grep"):
+        permissions.append(
+          {"action": action, "resource": "*", "effect": "allow"}
+        )
+
+    if context.permissions.allow_source_code_changes:
+      permissions.append(
+        {"action": "edit", "resource": "*", "effect": "allow"}
+      )
+    elif context.permissions.allow_spec_write:
+      permissions.append(
+        {"action": "edit", "resource": "*", "effect": "deny"}
+      )
+      permissions.append(
+        {
+          "action": "edit",
+          "resource": ".devflow/specs/**",
+          "effect": "allow",
+        }
+      )
+    else:
+      permissions.append(
+        {"action": "edit", "resource": "*", "effect": "deny"}
+      )
+
+    permissions.extend(
+      [
+        {
+          "action": "shell",
+          "resource": "*",
+          "effect": (
+            "allow"
+            if context.permissions.allow_source_code_changes
+            else "deny"
+          ),
+        },
+        {
+          "action": "question",
+          "resource": "*",
+          "effect": "allow" if interactive else "deny",
+        },
+        {"action": "webfetch", "resource": "*", "effect": "deny"},
+        {"action": "websearch", "resource": "*", "effect": "deny"},
+        {"action": "subagent", "resource": "*", "effect": "deny"},
+      ]
+    )
+    return permissions