deviatdd 2.5.1__py3-none-any.whl

deviate/state/ledger.py

@@ -0,0 +1,407 @@
+from __future__ import annotations
+
+import json
+import re
+import warnings
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Literal
+
+from pydantic import (
+    BaseModel,
+    Field,
+    ValidationError as PydanticValidationError,
+    field_validator,
+)
+
+try:
+    import fcntl
+
+    HAS_FCNTL = True
+except ImportError:
+    HAS_FCNTL = False
+
+
+class IssueRecord(BaseModel):
+    issue_id: str
+    type: str
+    title: str = Field(min_length=1)
+    status: Literal["DRAFT", "BACKLOG", "SPECIFIED", "SHARDED", "COMPLETED"] = "DRAFT"
+    source_file: str
+    blocked_by: list[str] = []
+    coordinates_with: list[str] = []
+    timestamp: datetime
+    created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    flow_refs: list[str] = Field(default_factory=list)
+
+    model_config = {"extra": "forbid"}
+
+
+def _read_ledger(path: Path) -> list[dict]:
+    if not path.exists():
+        return []
+    records: list[dict] = []
+    with path.open("r", encoding="utf-8") as f:
+        for line_no, line in enumerate(f, start=1):
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                records.append(json.loads(line))
+            except json.JSONDecodeError:
+                warnings.warn(
+                    f"Skipping malformed JSONL line {line_no} in {path}",
+                    stacklevel=2,
+                )
+                continue
+    return records
+
+
+class TaskRecord(BaseModel):
+    id: str
+    issue_id: str
+    description: str = Field(min_length=1)
+    status: Literal[
+        "PENDING",
+        "RED",
+        "GREEN",
+        "JUDGE",
+        "REFACTOR",
+        "COMPLETED",
+        "FAILED",
+    ] = "PENDING"
+    execution_mode: Literal["TDD", "DIRECT", "EXECUTE", "E2E", "IMMEDIATE"] = "TDD"
+    created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+
+    model_config = {"extra": "forbid"}
+
+    @field_validator("id")
+    @classmethod
+    def _validate_task_id(cls, v: str) -> str:
+        if not re.match(r"^TSK-\d{3}-\d{2}$", v):
+            raise ValueError(f"Invalid task ID format: {v}")
+        return v
+
+
+def _append_record(
+    record_json: str,
+    record_id: str,
+    id_field: str,
+    ledger_path: Path,
+) -> bool:
+    ledger_path.parent.mkdir(parents=True, exist_ok=True)
+    with ledger_path.open("a+", encoding="utf-8") as f:
+        if HAS_FCNTL:
+            fcntl.flock(f.fileno(), fcntl.LOCK_EX)
+        try:
+            f.seek(0)
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    data = json.loads(line)
+                    if data.get(id_field) == record_id:
+                        return False
+                except json.JSONDecodeError:
+                    continue
+            f.write(record_json + "\n")
+        finally:
+            if HAS_FCNTL:
+                fcntl.flock(f.fileno(), fcntl.LOCK_UN)
+    return True
+
+
+def _append_with_compound_key(
+    record_json: str,
+    key_fields: list[str],
+    ledger_path: Path,
+) -> bool:
+    """Append a record only if no existing entry matches all *key_fields* values."""
+    ledger_path.parent.mkdir(parents=True, exist_ok=True)
+    record_data = json.loads(record_json)
+    with ledger_path.open("a+", encoding="utf-8") as f:
+        if HAS_FCNTL:
+            fcntl.flock(f.fileno(), fcntl.LOCK_EX)
+        try:
+            f.seek(0)
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    data = json.loads(line)
+                    if all(data.get(k) == record_data.get(k) for k in key_fields):
+                        return False
+                except json.JSONDecodeError:
+                    continue
+            f.write(record_json + "\n")
+        finally:
+            if HAS_FCNTL:
+                fcntl.flock(f.fileno(), fcntl.LOCK_UN)
+    return True
+
+
+def append_issue_transition(record: IssueRecord, ledger_path: Path) -> bool:
+    """Append a status-transition entry for an issue.
+
+    Idempotency is checked on the ``(issue_id, status)`` compound key so that
+    multiple transitions for the same issue (e.g. BACKLOG → CLAIMED →
+    COMPLETED) are all recorded, but re-running the same transition is safe.
+    """
+    return _append_with_compound_key(
+        record_json=record.model_dump_json(),
+        key_fields=["issue_id", "status"],
+        ledger_path=ledger_path,
+    )
+
+
+def append_task_record(record: TaskRecord, ledger_path: Path) -> bool:
+    return _append_record(
+        record_json=record.model_dump_json(),
+        record_id=record.id,
+        id_field="id",
+        ledger_path=ledger_path,
+    )
+
+
+def append_task_transition(record: TaskRecord, ledger_path: Path) -> bool:
+    """Append a status-transition entry for a task.
+
+    Idempotency is checked on the ``(id, status)`` compound key so that
+    multiple transitions for the same task (e.g. PENDING → RED → GREEN)
+    are all recorded, but re-running the same transition is safe.
+    """
+    return _append_with_compound_key(
+        record_json=record.model_dump_json(),
+        key_fields=["id", "status"],
+        ledger_path=ledger_path,
+    )
+
+
+def resolve_issue_record(issue_id: str, ledger_path: Path) -> IssueRecord | None:
+    """Resolve the authoritative record for *issue_id*.
+
+    ``COMPLETED`` is a terminal status and always takes precedence over later
+    non-``COMPLETED`` entries: once an issue has been recorded ``COMPLETED``,
+    no subsequent ``SPECIFIED`` / ``BACKLOG`` / ``DRAFT`` transition overrides
+    it — even if that transition appears later in the ledger. This guards
+    against merge flows that re-append a non-terminal transition after the
+    ``COMPLETED`` write, and against idempotent merges whose write order is
+    non-monotonic.
+
+    Among non-``COMPLETED`` entries, the most recent valid record by file
+    position wins (the prior behaviour).
+
+    Tolerates sparse transitions (e.g. bare ``{issue_id, status, timestamp}``
+    written by external tools like squash-merge) by merging them with the
+    last fully-resolved record so they are not silently dropped by Pydantic
+    validation.
+    """
+    records = _read_ledger(ledger_path)
+    fallback: IssueRecord | None = None
+    base: IssueRecord | None = None
+
+    def _resolve_base(exclude: dict) -> IssueRecord | None:
+        for prev in reversed(records):
+            if prev.get("issue_id") != issue_id or prev is exclude:
+                continue
+            try:
+                return IssueRecord.model_validate(prev)
+            except PydanticValidationError:
+                continue
+        return None
+
+    for data in reversed(records):
+        if data.get("issue_id") != issue_id:
+            continue
+        try:
+            candidate = IssueRecord.model_validate(data)
+        except PydanticValidationError:
+            # Sparse transition — resolve base on first need.
+            if base is None:
+                base = _resolve_base(data)
+            if base is None:
+                continue
+            merged = {**base.model_dump(), **data}
+            try:
+                candidate = IssueRecord.model_validate(merged)
+            except PydanticValidationError:
+                continue
+        # COMPLETED is terminal — return immediately, regardless of file order.
+        if candidate.status == "COMPLETED":
+            return candidate
+        # Track the latest non-COMPLETED candidate as a fallback.
+        if fallback is None:
+            fallback = candidate
+
+    return fallback
+
+
+def append_issue_record(record: IssueRecord, ledger_path: Path) -> bool:
+    return _append_record(
+        record_json=record.model_dump_json(),
+        record_id=record.issue_id,
+        id_field="issue_id",
+        ledger_path=ledger_path,
+    )
+
+
+class LedgerFilter(BaseModel):
+    entity_type: Literal["issue", "task"]
+    status_filter: str | None = None
+    limit: int = Field(default=20, gt=0)
+    offset: int = Field(default=0, ge=0)
+    sort_by: Literal["created_at", "timestamp", "status"] = "created_at"
+    sort_desc: bool = True
+    model_config = {"extra": "forbid"}
+
+
+def _read_ledger_strict(path: Path) -> list[dict]:
+    if not path.exists():
+        return []
+    records: list[dict] = []
+    with path.open("r", encoding="utf-8") as f:
+        for line_no, line in enumerate(f, start=1):
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                records.append(json.loads(line))
+            except json.JSONDecodeError:
+                raise ValueError(f"Malformed JSONL line {line_no} in {path}")
+    return records
+
+
+def filter_tasks(ledger_path: Path, filter_obj: LedgerFilter) -> list[TaskRecord]:
+    records = _read_ledger_strict(ledger_path)
+    seen: set[str] = set()
+    deduped: list[dict] = []
+    for rec in records:
+        task_id = rec.get("id")
+        if task_id and task_id in seen:
+            continue
+        if task_id:
+            seen.add(task_id)
+        deduped.append(rec)
+    if filter_obj.status_filter:
+        deduped = [r for r in deduped if r.get("status") == filter_obj.status_filter]
+    sort_key = filter_obj.sort_by
+    deduped.sort(
+        key=lambda r: r.get(sort_key, "") or "",
+        reverse=filter_obj.sort_desc,
+    )
+    start = filter_obj.offset
+    end = start + filter_obj.limit
+    result = deduped[start:end]
+    tasks: list[TaskRecord] = []
+    for r in result:
+        try:
+            tasks.append(TaskRecord.model_validate(r))
+        except PydanticValidationError as e:
+            warnings.warn(f"Skipping invalid task record: {e}")
+            continue
+    return tasks
+
+
+class RollbackSnapshot(BaseModel):
+    phase: str
+    branch: str
+    commit_sha: str = Field(pattern=r"^[a-f0-9]{40}$")
+    red_sha: str = Field(pattern=r"^[a-f0-9]{40}$")
+    timestamp: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    reason: str
+    restored: bool = False
+    model_config = {"extra": "forbid"}
+
+
+ROLLBACK_LEDGER_NAME = "rollback.jsonl"
+
+
+def append_rollback_snapshot(snapshot: RollbackSnapshot, deviate_dir: Path) -> bool:
+    """Persist a RollbackSnapshot to .deviate/rollback.jsonl.
+
+    Idempotency is checked on the (phase, commit_sha) compound key so that
+    re-running the same rollback does not create duplicate entries.
+    """
+    ledger_path = deviate_dir / ROLLBACK_LEDGER_NAME
+    return _append_with_compound_key(
+        record_json=snapshot.model_dump_json(),
+        key_fields=["phase", "commit_sha"],
+        ledger_path=ledger_path,
+    )
+
+
+class AdhocRecord(BaseModel):
+    issue_id: str = Field(min_length=1)
+    description: str = Field(min_length=1)
+    execution_mode: Literal["TDD", "DIRECT", "EXECUTE", "E2E", "IMMEDIATE"] = "DIRECT"
+    status: Literal["PENDING", "COMPLETED"] = "PENDING"
+    timestamp: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    flow_refs: list[str] = Field(default_factory=list)
+
+    model_config = {"extra": "forbid"}
+
+
+def _parse_timestamp(value: object) -> datetime:
+    """Parse an ISO 8601 timestamp string to a timezone-aware datetime.
+
+    Returns ``datetime.min`` (UTC) for unparseable or missing values so that
+    malformed entries sort to the bottom rather than crashing the comparator.
+    """
+    if not isinstance(value, str):
+        return datetime.min.replace(tzinfo=timezone.utc)
+    try:
+        return datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except (ValueError, TypeError):
+        return datetime.min.replace(tzinfo=timezone.utc)
+
+
+def _get_unblocked_backlog_features(ledger_path: Path) -> list[IssueRecord]:
+    records = _read_ledger(ledger_path)
+    if not records:
+        return []
+
+    status_map: dict[str, str] = {}
+    for data in records:
+        issue_id = data.get("issue_id")
+        status = data.get("status")
+        if issue_id and status:
+            status_map[issue_id] = status
+
+    typed: list[dict] = [r for r in records if r.get("type") is not None]
+    issue_map: dict[str, dict] = {}
+    for f in typed:
+        issue_map[f["issue_id"]] = f
+
+    candidates: list[IssueRecord] = []
+    for issue_id, record in issue_map.items():
+        latest_status = status_map.get(issue_id, "BACKLOG")
+        if latest_status != "BACKLOG":
+            continue
+        blocked_by = record.get("blocked_by", [])
+        is_unblocked = True
+        for dep_id in blocked_by:
+            dep_status = status_map.get(dep_id, "UNKNOWN")
+            if dep_status != "COMPLETED":
+                is_unblocked = False
+                break
+        if is_unblocked:
+            candidates.append(IssueRecord.model_validate(record))
+
+    candidates.sort(key=lambda r: r.created_at or r.timestamp)
+    return candidates
+
+
+def select_next_unblocked_issue(ledger_path: Path) -> IssueRecord | None:
+    candidates = _get_unblocked_backlog_features(ledger_path)
+    return candidates[0] if candidates else None
+
+
+def select_unblocked_candidates(ledger_path: Path) -> list[IssueRecord]:
+    """Return all unblocked BACKLOG issue records, sorted oldest-first.
+
+    Multi-candidate version of ``select_next_unblocked_issue`` used by the
+    try-claim loop in the specify pre command.
+    """
+    return _get_unblocked_backlog_features(ledger_path)

deviate/ui/__init__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from deviate.ui.monitor import MarkdownStatus, OrchestrationMonitor, TaskStatus
+
+__all__ = ["MarkdownStatus", "OrchestrationMonitor", "TaskStatus"]

deviate/ui/monitor.py

@@ -0,0 +1,187 @@
+from __future__ import annotations
+
+from collections import deque
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any
+
+
+def _resolve_task_id(data: dict[str, Any]) -> str:
+    return data.get("id", data.get("task_id", ""))
+
+
+class MarkdownStatus(str, Enum):
+    PENDING = "[ ]"
+    IN_PROGRESS = "[/]"
+    COMPLETED = "[X]"
+    FAILED = "[✗]"
+
+
+VALID_EVENT_TYPES = frozenset(
+    {
+        "task_started",
+        "phase_change",
+        "task_completed",
+        "task_failed",
+        "pipeline_halted",
+        "pipeline_complete",
+        "agent_output",
+    }
+)
+
+
+@dataclass
+class TaskStatus:
+    id: str
+    description: str
+    marker: MarkdownStatus = MarkdownStatus.PENDING
+    phase: str = ""
+    error_reason: str | None = None
+
+
+class OrchestrationMonitor:
+    def __init__(
+        self,
+        console: Any,
+        *,
+        json_mode: bool = False,
+        total_tasks: int = 0,
+        verbose: bool = False,
+    ) -> None:
+        self._console = console
+        self._json_mode = json_mode
+        self._total_tasks = total_tasks
+        self._verbose = verbose
+        self._tasks: dict[str, TaskStatus] = {}
+        self._interrupted = False
+        self._exited = False
+        self.display_active = False
+        self._agent_output_buffer: deque[str] = deque(maxlen=5)
+        self._current_phase: str = "PENDING"
+        self._dispatch: dict[str, Any] = {
+            "task_started": self._on_task_started,
+            "phase_change": self._on_phase_change,
+            "task_completed": self._on_task_completed,
+            "task_failed": self._on_task_failed,
+            "pipeline_complete": self._on_pipeline_complete,
+            "agent_output": self._on_agent_output,
+        }
+
+    def __enter__(self) -> OrchestrationMonitor:
+        self._exited = False
+        self.display_active = True
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        if self._exited:
+            return
+        self._exited = True
+        self.display_active = False
+
+    def _validate_event(self, event_type: str) -> None:
+        if event_type not in VALID_EVENT_TYPES:
+            raise ValueError(f"Unknown event type: {event_type}")
+
+    def push_event(self, event_type: str, **data: Any) -> None:
+        self._validate_event(event_type)
+        if event_type == "agent_output" and not self._verbose:
+            if self._agent_output_buffer is not None:
+                line = data.get("line", "")
+                if line:
+                    self._agent_output_buffer.append(line)
+            return
+        handler = self._dispatch.get(event_type)
+        if handler is not None:
+            handler(data)
+        if self._json_mode:
+            from deviate.ui.render import emit_jsonl
+
+            emit_jsonl(event_type, **data)
+
+    def _on_task_started(self, data: dict[str, Any]) -> None:
+        task_id = _resolve_task_id(data)
+        self._agent_output_buffer.clear()
+        if (
+            task_id in self._tasks
+            and self._tasks[task_id].marker is not MarkdownStatus.PENDING
+        ):
+            return
+        self._tasks[task_id] = TaskStatus(
+            id=task_id,
+            description=data.get("description", ""),
+            marker=MarkdownStatus.IN_PROGRESS,
+            phase=data.get("phase", ""),
+        )
+
+    def _on_phase_change(self, data: dict[str, Any]) -> None:
+        task_id = _resolve_task_id(data)
+        phase = data.get("phase", "")
+        self._current_phase = phase
+        if task_id not in self._tasks:
+            self._tasks[task_id] = TaskStatus(
+                id=task_id,
+                description=data.get("description", ""),
+                marker=MarkdownStatus.IN_PROGRESS,
+                phase=phase,
+            )
+            return
+        self._tasks[task_id].phase = phase
+        if self._tasks[task_id].marker is MarkdownStatus.PENDING:
+            self._tasks[task_id].marker = MarkdownStatus.IN_PROGRESS
+
+    def _on_task_completed(self, data: dict[str, Any]) -> None:
+        task_id = _resolve_task_id(data)
+        if task_id not in self._tasks:
+            self._tasks[task_id] = TaskStatus(
+                id=task_id,
+                description=data.get("description", ""),
+                marker=MarkdownStatus.COMPLETED,
+                phase=data.get("phase", ""),
+            )
+            return
+        self._tasks[task_id].marker = MarkdownStatus.COMPLETED
+        self._tasks[task_id].phase = data.get("phase", self._tasks[task_id].phase)
+
+    def _on_task_failed(self, data: dict[str, Any]) -> None:
+        task_id = _resolve_task_id(data)
+        if task_id not in self._tasks:
+            self._tasks[task_id] = TaskStatus(
+                id=task_id,
+                description=data.get("description", ""),
+                marker=MarkdownStatus.FAILED,
+                error_reason=data.get("error_reason", ""),
+                phase=data.get("phase", ""),
+            )
+            return
+        self._tasks[task_id].marker = MarkdownStatus.FAILED
+        self._tasks[task_id].error_reason = data.get("error_reason", "")
+        self._tasks[task_id].phase = data.get("phase", self._tasks[task_id].phase)
+
+    def _on_agent_output(self, data: dict[str, Any]) -> None:
+        line = data.get("line", "")
+        if line:
+            self._agent_output_buffer.append(line)
+
+    def _on_pipeline_complete(self, data: dict[str, Any]) -> None:
+        self.display_active = False
+
+    def render(self) -> None:
+        pass
+
+    def get_task_phase(self, task_id: str) -> str:
+        task = self._tasks.get(task_id)
+        return task.phase if task else ""
+
+    @property
+    def failed_count(self) -> int:
+        return sum(1 for t in self._tasks.values() if t.marker is MarkdownStatus.FAILED)
+
+    def signal_keyboard_interrupt(self) -> None:
+        self._interrupted = True
+        for task in self._tasks.values():
+            if task.marker is MarkdownStatus.IN_PROGRESS:
+                task.marker = MarkdownStatus.FAILED
+
+    @property
+    def interrupted(self) -> bool:
+        return self._interrupted

deviate/ui/render.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+import json
+import os
+import sys
+from datetime import datetime, timezone
+from typing import Any
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def emit_jsonl(event: str, **fields: Any) -> None:
+    data = {"event": event, "timestamp": _now_iso(), **fields}
+    sys.stdout.write(json.dumps(data) + "\n")
+    sys.stdout.flush()
+
+
+def is_interactive() -> bool:
+    if os.environ.get("CI"):
+        return False
+    try:
+        return os.isatty(sys.stdout.fileno())
+    except (OSError, AttributeError):
+        return False