devflow-toolkit 0.3.0__py3-none-any.whl

devflow/core/ports.py

@@ -0,0 +1,159 @@
+"""Ports and data contracts for harness-independent workflows."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Protocol
+
+from devflow.core.config import AgentPermissions, DevFlowConfig
+from devflow.core.constitution import Constitution
+from devflow.models.profile import Profile
+from devflow.models.project import Project
+
+
+class AdapterError(Exception):
+  """Raised when a harness adapter cannot prepare or run an agent."""
+
+
+class HarnessExecutionError(AdapterError):
+  """Raised when the harness executable cannot be started."""
+
+
+@dataclass(frozen=True)
+class SetupContext:
+  """Project information needed to generate harness integration files."""
+
+  root: Path
+  project: Project
+  config: DevFlowConfig
+  profiles: tuple[Profile, ...]
+  constitution: Constitution
+  permissions: AgentPermissions
+
+  @property
+  def constitution_files(self) -> tuple[str, ...]:
+    """Return the constitution filenames in profile order."""
+    return tuple(
+      document.name for document in self.constitution.documents
+    )
+
+
+@dataclass(frozen=True)
+class RunContext:
+  """Information needed to invoke a harness for one specification."""
+
+  root: Path
+  prompt: str
+  spec_directory: Path
+  spec_path: Path
+  mode: str
+  permissions: AgentPermissions
+  output_path: Path | None = None
+
+
+@dataclass(frozen=True)
+class FileChange:
+  """A file created, updated or skipped during harness setup."""
+
+  path: Path
+  status: str
+
+
+@dataclass(frozen=True)
+class SetupResult:
+  """Outcome of generating the integration files for one harness."""
+
+  changes: tuple[FileChange, ...] = field(default_factory=tuple)
+  warnings: tuple[str, ...] = field(default_factory=tuple)
+
+  def add(self, change: FileChange) -> SetupResult:
+    """Return a new result with an additional file change."""
+    return SetupResult(
+      changes=(*self.changes, change),
+      warnings=self.warnings,
+    )
+
+
+@dataclass(frozen=True)
+class Invocation:
+  """A fully prepared harness process invocation."""
+
+  argv: tuple[str, ...]
+  cwd: Path
+  interactive: bool
+  stdin_text: str | None = None
+  output_path: Path | None = None
+
+
+@dataclass(frozen=True)
+class InvocationResult:
+  """Captured result of a harness invocation."""
+
+  returncode: int
+  stdout: str
+  stderr: str
+  output_path: Path | None = None
+
+  @property
+  def file_output(self) -> str:
+    """Return the adapter-provided output file contents, if any."""
+    if self.output_path is None or not self.output_path.is_file():
+      return ""
+    try:
+      return self.output_path.read_text(encoding="utf-8")
+    except OSError:
+      return ""
+
+
+class HarnessPort(ABC):
+  """Provider-independent interface implemented by each harness."""
+
+  name: str
+  display_name: str
+
+  @abstractmethod
+  def is_available(self) -> bool:
+    """Return whether the harness executable is available."""
+
+  @abstractmethod
+  def setup(self, context: SetupContext) -> SetupResult:
+    """Generate the integration files for this harness."""
+
+  @abstractmethod
+  def build_run(self, context: RunContext) -> Invocation:
+    """Build the process invocation for a specification request."""
+
+  def permission_warnings(
+    self,
+    context: RunContext,
+  ) -> tuple[str, ...]:
+    """Return limitations of the technical permission enforcement."""
+    return ()
+
+
+class InvocationExecutor(Protocol):
+  """Executes a prepared harness invocation."""
+
+  def __call__(self, invocation: Invocation) -> InvocationResult:
+    """Run the invocation and return its captured result."""
+
+
+def build_setup_context(
+  *,
+  config: DevFlowConfig,
+  project: Project,
+  profiles: list[Profile] | tuple[Profile, ...],
+  constitution: Constitution,
+  permissions: AgentPermissions | None = None,
+) -> SetupContext:
+  """Build the shared setup context for a harness adapter."""
+  return SetupContext(
+    root=config.root,
+    project=project,
+    config=config,
+    profiles=tuple(profiles),
+    constitution=constitution,
+    permissions=permissions or config.permissions,
+  )

devflow/core/profile_manager.py

@@ -0,0 +1,311 @@
+"""Discovery, loading and installation of project profiles."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+
+import yaml
+
+from devflow.core.project import canonicalize_dependency
+from devflow.models.profile import Profile
+from devflow.models.project import Project
+
+_GENERIC_DETECTION_FILES = {
+  "pyproject.toml",
+  "package.json",
+  "requirements.txt",
+}
+
+_BASE_PROFILE = "base"
+
+
+class ProfileError(Exception):
+  """Raised when a profile cannot be loaded or installed."""
+
+
+@dataclass(frozen=True)
+class ProfileMatch:
+  """A profile detected from project signals."""
+
+  profile: Profile
+  reasons: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class ConstitutionInstall:
+  """Result of installing constitution files into a project."""
+
+  copied: tuple[str, ...]
+  skipped: tuple[str, ...]
+
+
+class ProfileManager:
+  """Load bundled profiles and detect the ones applicable to a project."""
+
+  def __init__(self, profiles_root: Path | None = None) -> None:
+    self.profiles_root = (
+      profiles_root
+      or Path(__file__).resolve().parent.parent / "profiles"
+    )
+
+  def available(self) -> dict[str, Profile]:
+    """Return all bundled profiles indexed by name."""
+    if not self.profiles_root.is_dir():
+      msg = f"Profiles directory not found: {self.profiles_root}"
+      raise ProfileError(msg)
+
+    profiles: dict[str, Profile] = {}
+    for manifest_path in sorted(
+      self.profiles_root.glob("*/profile.yaml")
+    ):
+      profile = self._load_manifest(manifest_path)
+      profiles[profile.name] = profile
+
+    if _BASE_PROFILE not in profiles:
+      msg = f"Base profile not found in {self.profiles_root}"
+      raise ProfileError(msg)
+    return profiles
+
+  def names(self) -> list[str]:
+    """Return the names of all available profiles."""
+    return sorted(self.available())
+
+  def resolve(self, names: list[str]) -> list[Profile]:
+    """Resolve profile names, always including the base profile."""
+    available = self.available()
+    selected: list[str] = []
+    for name in names:
+      if name and name != _BASE_PROFILE and name not in selected:
+        selected.append(name)
+
+    unknown = sorted(set(selected) - set(available))
+    if unknown:
+      known = ", ".join(sorted(available))
+      msg = (
+        f"Unknown profile(s): {', '.join(unknown)}. "
+        f"Available profiles: {known}"
+      )
+      raise ProfileError(msg)
+
+    ordered: list[Profile] = [available[_BASE_PROFILE]]
+    ordered.extend(available[name] for name in selected)
+    return ordered
+
+  def detect(self, project: Project) -> list[ProfileMatch]:
+    """Detect profiles using dependency and file indicators."""
+    matches: list[ProfileMatch] = []
+    for profile in self.available().values():
+      if profile.name == _BASE_PROFILE:
+        continue
+
+      reasons: list[str] = []
+      dependencies = [
+        dependency
+        for dependency in profile.detection_dependencies
+        if self._dependency_present(
+          project.dependencies,
+          dependency,
+        )
+      ]
+      if dependencies:
+        reasons.extend(
+          f"dependency: {dependency}"
+          for dependency in dependencies
+        )
+
+      files = [
+        filename
+        for filename in profile.detection_files
+        if (project.root / filename).exists()
+      ]
+      strong_files = [
+        filename
+        for filename in files
+        if filename not in _GENERIC_DETECTION_FILES
+      ]
+
+      if not reasons and strong_files:
+        reasons.extend(f"file: {filename}" for filename in strong_files)
+
+      if reasons:
+        matches.append(
+          ProfileMatch(profile=profile, reasons=tuple(reasons))
+        )
+
+    return matches
+
+  def install_constitution(
+    self,
+    root: Path,
+    profiles: list[Profile],
+    destination: Path | None = None,
+  ) -> ConstitutionInstall:
+    """Copy profile constitution files without overwriting project files."""
+    resolved_root = root.resolve()
+    target_directory = (
+      destination or resolved_root / ".devflow" / "constitution"
+    ).resolve()
+    try:
+      target_directory.relative_to(resolved_root)
+    except ValueError as error:
+      msg = (
+        "Constitution destination must stay inside the project root: "
+        f"{target_directory}"
+      )
+      raise ProfileError(msg) from error
+
+    target_directory.mkdir(parents=True, exist_ok=True)
+    resolved_target = target_directory.resolve()
+    if resolved_target != target_directory:
+      msg = (
+        "Constitution destination changed while it was being created: "
+        f"{target_directory}"
+      )
+      raise ProfileError(msg)
+    target_directory = resolved_target
+
+    copied: list[str] = []
+    skipped: list[str] = []
+    seen: set[str] = set()
+
+    for profile in profiles:
+      for raw_filename in profile.constitution:
+        filename = self._constitution_name(raw_filename, profile)
+        if filename in seen:
+          msg = (
+            f"Duplicate constitution file '{filename}' in profile "
+            f"'{profile.name}'."
+          )
+          raise ProfileError(msg)
+        seen.add(filename)
+
+        source = (
+          profile.path.resolve() / "constitution" / filename
+        ).resolve()
+        try:
+          source.relative_to(profile.path.resolve())
+        except ValueError as error:
+          msg = (
+            f"Constitution file '{filename}' escapes profile "
+            f"'{profile.name}'."
+          )
+          raise ProfileError(msg) from error
+        if not source.is_file():
+          msg = (
+            f"Constitution file '{filename}' is missing from profile "
+            f"'{profile.name}'."
+          )
+          raise ProfileError(msg)
+
+        target = target_directory / filename
+        if target.exists() or target.is_symlink():
+          skipped.append(filename)
+          continue
+
+        if not self._copy_exclusive(source, target):
+          skipped.append(filename)
+          continue
+        copied.append(filename)
+
+    return ConstitutionInstall(
+      copied=tuple(copied),
+      skipped=tuple(skipped),
+    )
+
+  def constitution_documents(
+    self,
+    profiles: list[Profile],
+  ) -> list[str]:
+    """Return constitution filenames in profile order."""
+    return [
+      self._constitution_name(filename, profile)
+      for profile in profiles
+      for filename in profile.constitution
+    ]
+
+  def _constitution_name(self, filename: str, profile: Profile) -> str:
+    """Validate a profile constitution entry as a plain file name."""
+    if not isinstance(filename, str) or not filename.strip():
+      msg = (
+        f"Profile '{profile.name}' declares an empty constitution "
+        "file name."
+      )
+      raise ProfileError(msg)
+
+    name = filename.strip()
+    if (
+      name in {".", ".."}
+      or "/" in name
+      or "\\" in name
+      or "\x00" in name
+    ):
+      msg = (
+        f"Profile '{profile.name}' declares an invalid constitution "
+        f"file name: {filename!r}."
+      )
+      raise ProfileError(msg)
+    return name
+
+  def _copy_exclusive(self, source: Path, target: Path) -> bool:
+    """Copy a file atomically without replacing an existing target."""
+    descriptor, temporary_name = tempfile.mkstemp(
+      prefix=f".{target.name}-",
+      suffix=".tmp",
+      dir=target.parent,
+    )
+    temporary = Path(temporary_name)
+    try:
+      with os.fdopen(descriptor, "wb") as output:
+        with source.open("rb") as input_handle:
+          shutil.copyfileobj(input_handle, output)
+        output.flush()
+        os.fsync(output.fileno())
+      try:
+        mode = source.stat().st_mode & 0o777
+        os.chmod(temporary, mode or 0o644)
+      except OSError:
+        pass
+      try:
+        os.link(temporary, target)
+      except FileExistsError:
+        return False
+      return True
+    finally:
+      temporary.unlink(missing_ok=True)
+
+  def _load_manifest(self, path: Path) -> Profile:
+    try:
+      with path.open(encoding="utf-8") as handle:
+        data = yaml.safe_load(handle)
+    except OSError as error:
+      msg = f"Could not read profile manifest: {path}"
+      raise ProfileError(msg) from error
+    except yaml.YAMLError as error:
+      msg = f"Invalid YAML in profile manifest: {path}"
+      raise ProfileError(msg) from error
+
+    if not isinstance(data, dict):
+      msg = f"Profile manifest must contain a mapping: {path}"
+      raise ProfileError(msg)
+
+    try:
+      return Profile.from_manifest(path.parent, data)
+    except ValueError as error:
+      msg = f"Invalid profile manifest {path}: {error}"
+      raise ProfileError(msg) from error
+
+  def _dependency_present(
+    self,
+    project_dependencies: set[str],
+    profile_dependency: str,
+  ) -> bool:
+    canonical = canonicalize_dependency(profile_dependency)
+    return any(
+      dependency == canonical
+      or dependency.startswith(f"{canonical}-")
+      for dependency in project_dependencies
+    )