devflow-toolkit 0.3.0__py3-none-any.whl

devflow/core/config.py

@@ -0,0 +1,706 @@
+"""Reading and writing .devflow/config.yaml."""
+
+from __future__ import annotations
+
+import os
+import stat
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from devflow.models.project import (
+  PROJECT_MODES,
+  Project,
+  canonical_project_mode,
+)
+
+CONFIG_RELATIVE_PATH = Path(".devflow") / "config.yaml"
+DEFAULT_CONSTITUTION_PATH = Path(".devflow") / "constitution"
+DEFAULT_SPECIFICATIONS_PATH = Path(".devflow") / "specs"
+DEFAULT_PLANS_PATH = Path(".devflow") / "plans"
+DEFAULT_TEMPLATES_PATH = Path(".devflow") / "templates"
+
+SUPPORTED_HARNESSES = (
+  "auto",
+  "codex",
+  "opencode",
+  "claude-code",
+  "kiro",
+  "none",
+)
+EXECUTION_MODES = ("interactive", "non-interactive")
+
+_HARNESS_ALIASES = {
+  "claude": "claude-code",
+  "claude_code": "claude-code",
+  "claude-code": "claude-code",
+  "codex": "codex",
+  "kiro": "kiro",
+  "kiro-cli": "kiro",
+  "kiro_cli": "kiro",
+  "none": "none",
+  "off": "none",
+  "disabled": "none",
+  "auto": "auto",
+  "opencode": "opencode",
+}
+
+_CONFIG_HEADER = (
+  "# DevFlow project configuration.\n"
+  "# Generated by 'devflow init'. Review it before committing.\n"
+)
+
+
+class ConfigError(Exception):
+  """Raised when DevFlow configuration is missing or invalid."""
+
+
+def _preserve_mode(target: Path, temporary: Path) -> None:
+  """Keep an existing file mode, or use a conventional file mode."""
+  mode = 0o644
+  try:
+    mode = stat.S_IMODE(target.stat().st_mode)
+  except OSError:
+    pass
+  os.chmod(temporary, mode)
+
+
+def canonical_harness_name(value: str) -> str:
+  """Normalize a harness name or one of its accepted aliases."""
+  normalized = value.strip().lower()
+  return _HARNESS_ALIASES.get(normalized, normalized)
+
+
+def canonical_execution_mode(value: str) -> str:
+  """Normalize an execution mode name."""
+  normalized = value.strip().lower().replace("_", "-")
+  if normalized in {"noninteractive", "noninteractive-mode"}:
+    return "non-interactive"
+  return normalized
+
+
+def validate_document_name(value: str, field: str) -> str:
+  """Validate a constitution document name as a plain file name."""
+  if not isinstance(value, str) or not value.strip():
+    msg = f"{field} entries must be non-empty strings."
+    raise ConfigError(msg)
+
+  name = value.strip()
+  if (
+    name in {".", ".."}
+    or "/" in name
+    or "\\" in name
+    or "\x00" in name
+  ):
+    msg = (
+      f"{field} entries must be plain file names inside the constitution "
+      f"directory: {value!r}."
+    )
+    raise ConfigError(msg)
+  return name
+
+
+class _ConfigDumper(yaml.SafeDumper):
+  """Preserve indented YAML lists in generated configuration."""
+
+  def increase_indent(
+    self,
+    flow: bool = False,
+    indentless: bool = False,
+  ) -> None:
+    return super().increase_indent(flow, False)
+
+
+@dataclass(frozen=True)
+class ConstitutionSettings:
+  """Configuration for constitution files."""
+
+  path: Path
+  files: tuple[str, ...]
+  base: bool
+  profile_specific: bool
+
+
+@dataclass(frozen=True, init=False)
+class AgentPermissions:
+  """Capabilities granted to the configured agent harness.
+
+  ``allow_workflow_write`` is the canonical permission for DevFlow
+  artifacts. ``allow_spec_write`` is a read/write compatibility alias
+  for adapters and configuration written before workflow stages existed.
+  """
+
+  allow_project_read: bool = True
+  allow_workflow_write: bool = True
+  allow_source_code_changes: bool = False
+
+  def __init__(
+    self,
+    allow_project_read: bool = True,
+    allow_workflow_write: bool = True,
+    allow_source_code_changes: bool = False,
+    *,
+    allow_spec_write: bool | None = None,
+  ) -> None:
+    if allow_spec_write is not None:
+      allow_workflow_write = allow_spec_write
+    object.__setattr__(
+      self,
+      "allow_project_read",
+      allow_project_read,
+    )
+    object.__setattr__(
+      self,
+      "allow_workflow_write",
+      allow_workflow_write,
+    )
+    object.__setattr__(
+      self,
+      "allow_source_code_changes",
+      allow_source_code_changes,
+    )
+
+  @property
+  def allow_spec_write(self) -> bool:
+    """Compatibility alias for ``allow_workflow_write``."""
+    return self.allow_workflow_write
+
+
+@dataclass(frozen=True)
+class AgentSettings:
+  """Agent harness and execution preferences."""
+
+  harness: str = "auto"
+  execution_mode: str = "interactive"
+  permissions: AgentPermissions = AgentPermissions()
+
+
+@dataclass(frozen=True)
+class DevFlowConfig:
+  """Validated DevFlow configuration for a project."""
+
+  root: Path
+  path: Path
+  project_name: str
+  project_type: str
+  project_mode: str
+  profiles: tuple[str, ...]
+  technologies: dict[str, list[str]]
+  constitution: ConstitutionSettings
+  specifications_path: Path
+  plans_path: Path
+  templates_path: Path
+  agent: AgentSettings
+
+  @property
+  def agent_harness(self) -> str:
+    """Return the configured harness name."""
+    return self.agent.harness
+
+  @property
+  def execution_mode(self) -> str:
+    """Return the configured execution mode."""
+    return self.agent.execution_mode
+
+  @property
+  def permissions(self) -> AgentPermissions:
+    """Return the configured agent permissions."""
+    return self.agent.permissions
+
+
+class ConfigManager:
+  """Manage the persistent configuration of a DevFlow project."""
+
+  def __init__(self, root: Path) -> None:
+    self.root = root.resolve()
+    self.path = self.root / CONFIG_RELATIVE_PATH
+
+  def exists(self) -> bool:
+    """Return whether the project has a DevFlow configuration."""
+    return self._target_path().is_file()
+
+  def _target_path(self) -> Path:
+    """Resolve the configuration path without allowing symlink escapes."""
+    if self.path.is_symlink():
+      msg = (
+        "Configuration path must not be a symbolic link: "
+        f"{self.path}"
+      )
+      raise ConfigError(msg)
+
+    target = self.path.resolve()
+    try:
+      target.relative_to(self.root)
+    except ValueError as error:
+      msg = (
+        "Configuration path must stay inside the project root: "
+        f"{self.path}"
+      )
+      raise ConfigError(msg) from error
+    return target
+
+  def load(self) -> DevFlowConfig:
+    """Load and validate the project configuration."""
+    data = self._read_document()
+
+    project = self._mapping(data.get("project"), "project")
+    constitution = self._mapping(
+      data.get("constitution"),
+      "constitution",
+    )
+    specifications = self._mapping(
+      data.get("specifications"),
+      "specifications",
+    )
+    plans = self._mapping(data.get("plans"), "plans")
+    templates = self._mapping(
+      data.get("templates", {}),
+      "templates",
+    )
+    agent = self._mapping(data.get("agent", {}), "agent")
+    agent_settings = self._agent_settings(agent)
+
+    profiles = self._string_list(
+      data.get("profiles", []),
+      "profiles",
+    )
+
+    constitution_path = self._relative_path(
+      constitution.get("path", DEFAULT_CONSTITUTION_PATH.as_posix()),
+      "constitution.path",
+    )
+    specifications_path = self._relative_path(
+      specifications.get(
+        "path",
+        DEFAULT_SPECIFICATIONS_PATH.as_posix(),
+      ),
+      "specifications.path",
+    )
+    plans_path = self._relative_path(
+      plans.get("path", DEFAULT_PLANS_PATH.as_posix()),
+      "plans.path",
+    )
+    templates_path = self._relative_path(
+      templates.get("path", DEFAULT_TEMPLATES_PATH.as_posix()),
+      "templates.path",
+    )
+
+    technologies = self._technologies(data.get("technologies", {}))
+
+    name = project.get("name", self.root.name)
+    project_type = project.get("type", "unknown")
+    project_mode = canonical_project_mode(
+      str(project.get("mode", "existing")),
+    )
+    if not isinstance(name, str) or not name.strip():
+      msg = "project.name must be a non-empty string."
+      raise ConfigError(msg)
+    if not isinstance(project_type, str) or not project_type.strip():
+      msg = "project.type must be a non-empty string."
+      raise ConfigError(msg)
+    if project_mode not in PROJECT_MODES:
+      msg = (
+        f"project.mode must be one of: {', '.join(PROJECT_MODES)}."
+      )
+      raise ConfigError(msg)
+
+    return DevFlowConfig(
+      root=self.root,
+      path=self.path,
+      project_name=name.strip(),
+      project_type=project_type.strip(),
+      project_mode=project_mode,
+      profiles=tuple(profiles),
+      technologies=technologies,
+      constitution=ConstitutionSettings(
+        path=constitution_path,
+        files=tuple(
+          validate_document_name(item, "constitution.files")
+          for item in self._string_list(
+            constitution.get("files", []),
+            "constitution.files",
+          )
+        ),
+        base=self._boolean(
+          constitution.get("base", True),
+          "constitution.base",
+        ),
+        profile_specific=self._boolean(
+          constitution.get("profile_specific", True),
+          "constitution.profile_specific",
+        ),
+      ),
+      specifications_path=specifications_path,
+      plans_path=plans_path,
+      templates_path=templates_path,
+      agent=agent_settings,
+    )
+
+  def create(
+    self,
+    project: Project,
+    profiles: list[str],
+    constitution_files: list[str],
+    project_type: str | None = None,
+    project_mode: str = "existing",
+    agent_harness: str = "auto",
+    execution_mode: str = "interactive",
+    permissions: AgentPermissions | None = None,
+  ) -> DevFlowConfig:
+    """Create and persist a configuration for a project."""
+    normalized_project_mode = canonical_project_mode(project_mode)
+    if normalized_project_mode not in PROJECT_MODES:
+      msg = (
+        f"Unknown project mode: {project_mode}. "
+        f"Supported values: {', '.join(PROJECT_MODES)}."
+      )
+      raise ConfigError(msg)
+    harness = canonical_harness_name(agent_harness)
+    if harness not in SUPPORTED_HARNESSES:
+      msg = (
+        f"Unknown agent harness: {agent_harness}. "
+        f"Supported values: {', '.join(SUPPORTED_HARNESSES)}."
+      )
+      raise ConfigError(msg)
+    mode = canonical_execution_mode(execution_mode)
+    if mode not in EXECUTION_MODES:
+      msg = (
+        f"Unknown execution mode: {execution_mode}. "
+        f"Supported values: {', '.join(EXECUTION_MODES)}."
+      )
+      raise ConfigError(msg)
+    agent_permissions = permissions or AgentPermissions()
+    validated_files = [
+      validate_document_name(filename, "constitution_files")
+      for filename in constitution_files
+    ]
+
+    data = {
+      "project": {
+        "name": project.name,
+        "type": project_type or project.project_type,
+        "mode": normalized_project_mode,
+      },
+      "profiles": profiles,
+      "technologies": {
+        "languages": project.languages,
+        "frameworks": project.frameworks,
+        "databases": project.databases,
+      },
+      "constitution": {
+        "base": True,
+        "profile_specific": True,
+        "path": DEFAULT_CONSTITUTION_PATH.as_posix(),
+        "files": validated_files,
+      },
+      "specifications": {
+        "path": DEFAULT_SPECIFICATIONS_PATH.as_posix(),
+      },
+      "plans": {
+        "path": DEFAULT_PLANS_PATH.as_posix(),
+      },
+      "templates": {
+        "path": DEFAULT_TEMPLATES_PATH.as_posix(),
+      },
+      "agent": {
+        "harness": harness,
+        "execution": {
+          "mode": mode,
+        },
+        "permissions": {
+          "allow_project_read": (
+            agent_permissions.allow_project_read
+          ),
+          "allow_workflow_write": (
+            agent_permissions.allow_workflow_write
+          ),
+          "allow_spec_write": (
+            agent_permissions.allow_workflow_write
+          ),
+          "allow_source_code_changes": (
+            agent_permissions.allow_source_code_changes
+          ),
+        },
+      },
+    }
+
+    content = _CONFIG_HEADER + yaml.dump(
+      data,
+      Dumper=_ConfigDumper,
+      sort_keys=False,
+      allow_unicode=True,
+    )
+    self._write_atomic(content)
+    return self.load()
+
+  def set_agent_harness(
+    self,
+    harness: str,
+    execution_mode: str | None = None,
+  ) -> DevFlowConfig:
+    """Persist the selected harness and optional execution mode."""
+    canonical = canonical_harness_name(harness)
+    if canonical not in SUPPORTED_HARNESSES:
+      msg = (
+        f"Unknown agent harness: {harness}. "
+        f"Supported values: {', '.join(SUPPORTED_HARNESSES)}."
+      )
+      raise ConfigError(msg)
+
+    data = self._read_document()
+    agent = data.get("agent")
+    if not isinstance(agent, dict):
+      agent = {}
+      data["agent"] = agent
+    agent["harness"] = canonical
+
+    if execution_mode is not None:
+      mode = canonical_execution_mode(execution_mode)
+      if mode not in EXECUTION_MODES:
+        msg = (
+          f"Unknown execution mode: {execution_mode}. "
+          f"Supported values: {', '.join(EXECUTION_MODES)}."
+        )
+        raise ConfigError(msg)
+      execution = agent.get("execution")
+      if not isinstance(execution, dict):
+        execution = {}
+        agent["execution"] = execution
+      execution["mode"] = mode
+
+    self._write_document(data)
+    return self.load()
+
+  def set_execution_mode(self, execution_mode: str) -> DevFlowConfig:
+    """Persist the selected execution mode."""
+    config = self.load()
+    return self.set_agent_harness(
+      config.agent_harness,
+      execution_mode=execution_mode,
+    )
+
+  def set_project_mode(self, project_mode: str) -> DevFlowConfig:
+    """Persist the default project mode used by the next spec runs."""
+    normalized = canonical_project_mode(project_mode)
+    if normalized not in PROJECT_MODES:
+      msg = (
+        f"Unknown project mode: {project_mode}. "
+        f"Supported values: {', '.join(PROJECT_MODES)}."
+      )
+      raise ConfigError(msg)
+
+    data = self._read_document()
+    project = data.get("project")
+    if not isinstance(project, dict):
+      project = {}
+      data["project"] = project
+    project["mode"] = normalized
+    self._write_document(data)
+    return self.load()
+
+  def ensure_directories(self, config: DevFlowConfig) -> None:
+    """Create the directories referenced by the configuration."""
+    for path in (
+      config.constitution.path,
+      config.specifications_path,
+      config.plans_path,
+      config.templates_path,
+    ):
+      resolved = path.resolve()
+      try:
+        resolved.relative_to(self.root)
+      except ValueError as error:
+        msg = (
+          "Configured directory must stay inside the project root: "
+          f"{path}"
+        )
+        raise ConfigError(msg) from error
+      resolved.mkdir(parents=True, exist_ok=True)
+
+  def _read_document(self) -> dict[str, Any]:
+    target = self._target_path()
+    if not target.is_file():
+      msg = (
+        "DevFlow is not initialized in this project. "
+        "Run 'devflow init' first."
+      )
+      raise ConfigError(msg)
+
+    try:
+      with target.open(encoding="utf-8") as handle:
+        data = yaml.safe_load(handle)
+    except OSError as error:
+      msg = f"Could not read configuration: {self.path}"
+      raise ConfigError(msg) from error
+    except yaml.YAMLError as error:
+      msg = f"Invalid YAML in configuration: {self.path}"
+      raise ConfigError(msg) from error
+
+    if not isinstance(data, dict):
+      msg = "Configuration must contain a mapping."
+      raise ConfigError(msg)
+    return data
+
+  def _write_document(self, data: dict[str, Any]) -> None:
+    content = _CONFIG_HEADER + yaml.dump(
+      data,
+      Dumper=_ConfigDumper,
+      sort_keys=False,
+      allow_unicode=True,
+    )
+    self._write_atomic(content)
+
+  def _agent_settings(self, agent: dict[str, Any]) -> AgentSettings:
+    harness = canonical_harness_name(
+      str(agent.get("harness", "auto")),
+    )
+    if harness not in SUPPORTED_HARNESSES:
+      msg = (
+        f"agent.harness must be one of: "
+        f"{', '.join(SUPPORTED_HARNESSES)}."
+      )
+      raise ConfigError(msg)
+
+    execution = self._mapping(
+      agent.get("execution", {}),
+      "agent.execution",
+    )
+    mode = canonical_execution_mode(
+      str(execution.get("mode", "interactive")),
+    )
+    if mode not in EXECUTION_MODES:
+      msg = (
+        f"agent.execution.mode must be one of: "
+        f"{', '.join(EXECUTION_MODES)}."
+      )
+      raise ConfigError(msg)
+
+    permissions = self._mapping(
+      agent.get("permissions", {}),
+      "agent.permissions",
+    )
+    workflow_write = permissions.get("allow_workflow_write")
+    spec_write = permissions.get("allow_spec_write")
+    if workflow_write is None:
+      allow_workflow_write = (
+        True
+        if spec_write is None
+        else self._boolean(
+          spec_write,
+          "agent.permissions.allow_spec_write",
+        )
+      )
+    else:
+      allow_workflow_write = self._boolean(
+        workflow_write,
+        "agent.permissions.allow_workflow_write",
+      )
+    return AgentSettings(
+      harness=harness,
+      execution_mode=mode,
+      permissions=AgentPermissions(
+        allow_project_read=self._boolean(
+          permissions.get("allow_project_read", True),
+          "agent.permissions.allow_project_read",
+        ),
+        allow_workflow_write=allow_workflow_write,
+        allow_source_code_changes=self._boolean(
+          permissions.get("allow_source_code_changes", False),
+          "agent.permissions.allow_source_code_changes",
+        ),
+      ),
+    )
+
+  def _write_atomic(self, content: str) -> None:
+    target = self._target_path()
+    target.parent.mkdir(parents=True, exist_ok=True)
+    resolved_parent = target.parent.resolve()
+    try:
+      resolved_parent.relative_to(self.root)
+    except ValueError as error:
+      msg = (
+        "Configuration directory must stay inside the project root: "
+        f"{target.parent}"
+      )
+      raise ConfigError(msg) from error
+    target = resolved_parent / target.name
+
+    descriptor, temporary_name = tempfile.mkstemp(
+      prefix=".config-",
+      suffix=".yaml",
+      dir=target.parent,
+    )
+    temporary = Path(temporary_name)
+    try:
+      with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
+        handle.write(content)
+        handle.flush()
+        os.fsync(handle.fileno())
+      _preserve_mode(target, temporary)
+      temporary.replace(target)
+    finally:
+      temporary.unlink(missing_ok=True)
+
+  def _mapping(self, value: Any, field: str) -> dict[str, Any]:
+    if value is None:
+      return {}
+    if not isinstance(value, dict):
+      msg = f"{field} must be a mapping."
+      raise ConfigError(msg)
+    return value
+
+  def _string_list(self, value: Any, field: str) -> list[str]:
+    if value is None:
+      return []
+    if not isinstance(value, list) or not all(
+      isinstance(item, str)
+      for item in value
+    ):
+      msg = f"{field} must be a list of strings."
+      raise ConfigError(msg)
+    return list(value)
+
+  def _boolean(self, value: Any, field: str) -> bool:
+    if not isinstance(value, bool):
+      msg = f"{field} must be a boolean."
+      raise ConfigError(msg)
+    return value
+
+  def _technologies(self, value: Any) -> dict[str, list[str]]:
+    if value is None:
+      return {}
+    if not isinstance(value, dict):
+      msg = "technologies must be a mapping."
+      raise ConfigError(msg)
+
+    technologies: dict[str, list[str]] = {}
+    for key, items in value.items():
+      if not isinstance(key, str):
+        msg = "technology keys must be strings."
+        raise ConfigError(msg)
+      technologies[key] = self._string_list(
+        items,
+        f"technologies.{key}",
+      )
+    return technologies
+
+  def _relative_path(self, value: Any, field: str) -> Path:
+    if not isinstance(value, str) or not value.strip():
+      msg = f"{field} must be a non-empty path string."
+      raise ConfigError(msg)
+
+    path = Path(value)
+    if path.is_absolute():
+      msg = f"{field} must be relative to the project root."
+      raise ConfigError(msg)
+
+    resolved = (self.root / path).resolve()
+    try:
+      resolved.relative_to(self.root)
+    except ValueError as error:
+      msg = f"{field} must stay inside the project root."
+      raise ConfigError(msg) from error
+    return resolved