devflow-toolkit 0.3.0__py3-none-any.whl

devflow/core/artifacts/store.py

@@ -0,0 +1,130 @@
+"""Atomic artifact storage with normalized SHA-256 digests."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import tempfile
+from pathlib import Path
+
+from devflow.core.artifacts.errors import (
+  ArtifactError,
+  ArtifactNotFoundError,
+  ArtifactOutsideProjectError,
+  ArtifactWriteError,
+)
+
+
+class ArtifactStore:
+  """Read, write and verify project artifacts.
+
+  Text is normalized before it is written and before its digest is
+  computed. The digest therefore identifies the stored artifact, not a
+  temporary prompt or a raw agent response.
+  """
+
+  def __init__(self, root: Path) -> None:
+    self.root = root.resolve()
+
+  def normalize(self, content: str) -> str:
+    """Return the canonical stored form of a text artifact."""
+    text = content.lstrip("\ufeff")
+    text = text.replace("\r\n", "\n").replace("\r", "\n")
+    return text.rstrip() + "\n"
+
+  def digest_text(self, content: str) -> str:
+    """Return the SHA-256 digest of normalized text."""
+    normalized = self.normalize(content)
+    digest = hashlib.sha256(normalized.encode("utf-8")).hexdigest()
+    return f"sha256:{digest}"
+
+  def digest_file(self, path: Path) -> str:
+    """Return the digest of a stored artifact."""
+    return self.digest_text(self.read(path))
+
+  def read(self, path: Path) -> str:
+    """Read an artifact as normalized text."""
+    target = self._inside_project(path)
+    if not target.is_file():
+      raise ArtifactNotFoundError(
+        f"Artifact does not exist: {self.display_path(target)}"
+      )
+    try:
+      content = target.read_text(encoding="utf-8")
+    except UnicodeDecodeError as error:
+      msg = f"Artifact is not valid UTF-8: {self.display_path(target)}"
+      raise ArtifactError(msg) from error
+    except OSError as error:
+      msg = f"Could not read artifact: {self.display_path(target)}"
+      raise ArtifactError(msg) from error
+    return self.normalize(content)
+
+  def write(
+    self,
+    path: Path,
+    content: str,
+    *,
+    archive: bool = False,
+  ) -> str:
+    """Write normalized text atomically and return its digest."""
+    target = self._inside_project(path)
+    normalized = self.normalize(content)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    if archive and target.is_file():
+      self.archive(target)
+
+    descriptor, temporary_name = tempfile.mkstemp(
+      prefix=f".{target.name}-",
+      suffix=".tmp",
+      dir=target.parent,
+    )
+    temporary = Path(temporary_name)
+    try:
+      with os.fdopen(descriptor, "w", encoding="utf-8", newline="\n") as handle:
+        handle.write(normalized)
+        handle.flush()
+        os.fsync(handle.fileno())
+      temporary.replace(target)
+    except OSError as error:
+      msg = f"Could not write artifact: {self.display_path(target)}"
+      raise ArtifactWriteError(msg) from error
+    finally:
+      temporary.unlink(missing_ok=True)
+    return self.digest_text(normalized)
+
+  def verify(self, path: Path, expected_digest: str) -> bool:
+    """Return whether the stored artifact still matches a digest."""
+    try:
+      return self.digest_file(path) == expected_digest
+    except ArtifactError:
+      return False
+
+  def archive(self, path: Path) -> Path:
+    """Copy the current artifact into its history directory."""
+    target = self._inside_project(path)
+    content = self.read(target)
+    digest = self.digest_text(content)
+    short = digest.removeprefix("sha256:")[:12]
+    history = target.parent / "history"
+    history.mkdir(parents=True, exist_ok=True)
+    archived = history / f"{short}-{target.name}"
+    if not archived.is_file():
+      self.write(archived, content)
+    return archived
+
+  def display_path(self, path: Path) -> str:
+    """Return a project-relative path for messages."""
+    target = path.resolve()
+    try:
+      return target.relative_to(self.root).as_posix()
+    except ValueError:
+      return target.as_posix()
+
+  def _inside_project(self, path: Path) -> Path:
+    target = path.resolve()
+    try:
+      target.relative_to(self.root)
+    except ValueError as error:
+      msg = f"Artifact path escapes the project root: {target}"
+      raise ArtifactOutsideProjectError(msg) from error
+    return target

devflow/core/clock.py

@@ -0,0 +1,67 @@
+"""Small runtime contracts used by state and artifact components."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timezone
+from typing import Protocol
+
+
+class Clock(Protocol):
+  """Provides the current time."""
+
+  def now(self) -> datetime:
+    """Return the current UTC datetime."""
+
+
+class SystemClock:
+  """Clock backed by the system clock."""
+
+  def now(self) -> datetime:
+    return datetime.now(timezone.utc)
+
+
+class FixedClock:
+  """Deterministic clock for tests."""
+
+  def __init__(self, value: datetime) -> None:
+    self.value = value
+
+  def now(self) -> datetime:
+    return self.value
+
+
+class IdGenerator(Protocol):
+  """Generates stable identifiers for events and runs."""
+
+  def new_id(self, prefix: str) -> str:
+    """Return a new identifier with the given prefix."""
+
+
+class UuidIdGenerator:
+  """Identifier generator backed by UUID4."""
+
+  def new_id(self, prefix: str) -> str:
+    return f"{prefix}-{uuid.uuid4().hex[:12]}"
+
+
+class SequentialIdGenerator:
+  """Deterministic identifier generator for tests."""
+
+  def __init__(self) -> None:
+    self._counters: dict[str, int] = {}
+
+  def new_id(self, prefix: str) -> str:
+    current = self._counters.get(prefix, 0) + 1
+    self._counters[prefix] = current
+    return f"{prefix}-{current:03d}"
+
+
+def format_timestamp(value: datetime) -> str:
+  """Format a datetime as a stable UTC ISO-8601 timestamp."""
+  normalized = value
+  if normalized.tzinfo is None:
+    normalized = normalized.replace(tzinfo=timezone.utc)
+  else:
+    normalized = normalized.astimezone(timezone.utc)
+  return normalized.isoformat(timespec="seconds").replace("+00:00", "Z")