devflow-toolkit 0.3.0__py3-none-any.whl

devflow/core/state/locator.py

@@ -0,0 +1,116 @@
+"""Locate change directories inside the specifications path."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from devflow.core.state.errors import ChangeNotFoundError, StateError
+
+_CHANGE_PATTERN = re.compile(r"^(\d{3})-(.+)$")
+
+
+@dataclass(frozen=True)
+class ChangeLocation:
+  """One DevFlow change anchored by a specification directory."""
+
+  spec_id: str
+  change: str
+  directory: Path
+  @property
+  def workflow_path(self) -> Path:
+    return self.directory / "workflow.yaml"
+
+  @property
+  def events_path(self) -> Path:
+    return self.directory / "events.jsonl"
+
+  @property
+  def lock_path(self) -> Path:
+    return self.directory / ".lock"
+
+  @property
+  def runs_path(self) -> Path:
+    return self.directory / "runs"
+
+
+class WorkflowLocator:
+  """Resolve user selectors such as ``001`` or ``001-add-health``."""
+
+  def __init__(self, specs_path: Path) -> None:
+    self.specs_path = specs_path.resolve()
+
+  def find(self, selector: str) -> ChangeLocation:
+    """Return the change matching a selector."""
+    value = selector.strip()
+    if not value:
+      msg = "A change id or directory name is required."
+      raise ChangeNotFoundError(msg)
+
+    candidates: list[Path] = []
+    if value.isdigit():
+      prefix = f"{int(value):03d}-"
+      if self.specs_path.is_dir():
+        candidates = sorted(
+          child
+          for child in self.specs_path.iterdir()
+          if child.is_dir() and child.name.startswith(prefix)
+        )
+    else:
+      direct = Path(value)
+      if direct.is_absolute():
+        if direct.is_dir():
+          candidates = [direct]
+      else:
+        exact = self.specs_path / value
+        if exact.is_dir():
+          candidates = [exact]
+
+    if not candidates:
+      msg = (
+        f"Change '{selector}' was not found under "
+        f"{self.specs_path}."
+      )
+      raise ChangeNotFoundError(msg)
+    if len(candidates) > 1:
+      msg = (
+        f"Change selector '{selector}' is ambiguous. "
+        "Use the complete change directory name."
+      )
+      raise ChangeNotFoundError(msg)
+    return self.from_directory(candidates[0])
+
+  def list(self) -> tuple[ChangeLocation, ...]:
+    """Return all changes in stable order."""
+    if not self.specs_path.is_dir():
+      return ()
+    locations: list[ChangeLocation] = []
+    for child in sorted(self.specs_path.iterdir()):
+      if child.is_dir() and _CHANGE_PATTERN.match(child.name):
+        locations.append(self.from_directory(child))
+    return tuple(locations)
+
+  def from_directory(self, directory: Path) -> ChangeLocation:
+    """Build a location from a specification directory."""
+    resolved = directory.resolve()
+    try:
+      resolved.relative_to(self.specs_path)
+    except ValueError as error:
+      msg = (
+        f"Change directory is outside the specifications path: "
+        f"{resolved}"
+      )
+      raise StateError(msg) from error
+    match = _CHANGE_PATTERN.match(resolved.name)
+    if not match:
+      msg = (
+        f"Change directory must use the '<id>-<slug>' format: "
+        f"{resolved.name}"
+      )
+      raise StateError(msg)
+    return ChangeLocation(
+      spec_id=match.group(1),
+      change=resolved.name,
+      directory=resolved,
+    )

devflow/core/state/lock.py

@@ -0,0 +1,69 @@
+"""Advisory lock for operations on a single change."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from types import TracebackType
+
+try:
+  import fcntl
+except ImportError:  # pragma: no cover - DevFlow targets POSIX systems.
+  fcntl = None  # type: ignore[assignment]
+
+from devflow.core.state.errors import ChangeLockedError, StateError
+
+
+class ChangeLock:
+  """Exclusive, non-blocking lock scoped to one change directory."""
+
+  def __init__(self, path: Path, *, change: str = "") -> None:
+    self.path = path
+    self.change = change
+    self._handle: object | None = None
+
+  def acquire(self) -> ChangeLock:
+    """Acquire the lock or raise when another process holds it."""
+    if fcntl is None:  # pragma: no cover
+      msg = "Change locking requires a POSIX platform with fcntl."
+      raise StateError(msg)
+    self.path.parent.mkdir(parents=True, exist_ok=True)
+    handle = self.path.open("a+", encoding="utf-8")
+    try:
+      fcntl.flock(handle.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
+    except BlockingIOError as error:
+      handle.close()
+      label = f" change {self.change}" if self.change else " this change"
+      msg = (
+        f"Another DevFlow operation is already running for{label}. "
+        "Wait for it to finish and retry."
+      )
+      raise ChangeLockedError(msg) from error
+    except OSError as error:
+      handle.close()
+      msg = f"Could not lock change directory: {self.path}"
+      raise StateError(msg) from error
+    self._handle = handle
+    return self
+
+  def release(self) -> None:
+    """Release the lock when held."""
+    handle = self._handle
+    if handle is None:
+      return
+    self._handle = None
+    try:
+      if fcntl is not None:
+        fcntl.flock(handle.fileno(), fcntl.LOCK_UN)  # type: ignore[attr-defined]
+    finally:
+      handle.close()  # type: ignore[attr-defined]
+
+  def __enter__(self) -> ChangeLock:
+    return self.acquire()
+
+  def __exit__(
+    self,
+    exc_type: type[BaseException] | None,
+    exc: BaseException | None,
+    traceback: TracebackType | None,
+  ) -> None:
+    self.release()