codealmanac 0.1.0.dev0__py3-none-any.whl

codealmanac/workflows/lifecycle.py

@@ -0,0 +1,197 @@
+from pathlib import Path
+
+from codealmanac.core.errors import ExecutionFailed, ValidationFailed
+from codealmanac.core.models import CodeAlmanacModel
+from codealmanac.services.harnesses.models import (
+    HarnessEvent,
+    HarnessEventKind,
+    HarnessRunResult,
+    HarnessRunStatus,
+    terminal_harness_event,
+)
+from codealmanac.services.runs.models import RunEventKind
+from codealmanac.services.workspaces.models import (
+    Workspace,
+    WorkspaceChangeSnapshot,
+    WorkspacePathChange,
+)
+from codealmanac.services.workspaces.ports import WorkspaceChangeProbe
+
+
+class LifecycleMutationPreflight(CodeAlmanacModel):
+    before: WorkspaceChangeSnapshot
+    almanac_prefix: Path
+
+
+class LifecycleMutationReport(CodeAlmanacModel):
+    before: WorkspaceChangeSnapshot
+    after: WorkspaceChangeSnapshot
+    changed_files: tuple[Path, ...]
+
+
+class LifecycleMutationPolicy:
+    def __init__(self, probe: WorkspaceChangeProbe, operation: str):
+        self.probe = probe
+        self.operation = operation
+
+    def preflight(self, workspace: Workspace) -> LifecycleMutationPreflight:
+        before = self.probe.snapshot(workspace.root_path)
+        validate_snapshot_available(before, self.operation)
+        almanac_prefix = almanac_relative_path(workspace)
+        dirty_almanac = tuple(
+            change.path
+            for change in before.changes
+            if path_is_under(change.path, almanac_prefix)
+        )
+        if dirty_almanac:
+            almanac_label = almanac_prefix.as_posix()
+            raise ValidationFailed(
+                f"{self.operation} requires a clean {almanac_label} before running: "
+                f"{format_paths(dirty_almanac)}"
+            )
+        return LifecycleMutationPreflight(
+            before=before,
+            almanac_prefix=almanac_prefix,
+        )
+
+    def validate(
+        self,
+        preflight: LifecycleMutationPreflight,
+        workspace: Workspace,
+        reported_changed_files: tuple[Path, ...],
+    ) -> LifecycleMutationReport:
+        validate_reported_changes(workspace, reported_changed_files)
+        after = self.probe.snapshot(workspace.root_path)
+        validate_snapshot_available(after, self.operation)
+        mutated = changed_paths(preflight.before, after)
+        unsafe = tuple(
+            path
+            for path in mutated
+            if not path_is_under(path, preflight.almanac_prefix)
+        )
+        if unsafe:
+            almanac_label = preflight.almanac_prefix.as_posix()
+            raise ValidationFailed(
+                f"{self.operation} changed file outside {almanac_label}: "
+                f"{format_paths(unsafe)}"
+            )
+        return LifecycleMutationReport(
+            before=preflight.before,
+            after=after,
+            changed_files=tuple(
+                workspace.root_path / path
+                for path in mutated
+                if path_is_under(path, preflight.almanac_prefix)
+            ),
+        )
+
+
+def validate_harness_result(result: HarnessRunResult) -> None:
+    if result.status != HarnessRunStatus.SUCCEEDED:
+        suffix = first_line(result.output_text)
+        details = f": {suffix}" if suffix else ""
+        raise ExecutionFailed(
+            f"harness {result.kind.value} failed with status "
+            f"{result.status.value}{details}"
+        )
+
+
+def harness_events(result: HarnessRunResult) -> tuple[HarnessEvent, ...]:
+    if len(result.events) > 0:
+        return result.events
+    return (terminal_harness_event(result.kind, result.status, result.output_text),)
+
+
+def harness_run_event_kind(event: HarnessEvent) -> RunEventKind:
+    if event.kind == HarnessEventKind.ERROR:
+        return RunEventKind.ERROR
+    if event.kind in {
+        HarnessEventKind.TOOL_USE,
+        HarnessEventKind.TOOL_RESULT,
+        HarnessEventKind.TOOL_SUMMARY,
+        HarnessEventKind.CONTEXT_USAGE,
+        HarnessEventKind.WARNING,
+    }:
+        return RunEventKind.TOOL
+    return RunEventKind.OUTPUT
+
+
+def first_line(value: str) -> str:
+    return value.splitlines()[0] if value.splitlines() else value
+
+
+def validate_snapshot_available(
+    snapshot: WorkspaceChangeSnapshot,
+    operation: str,
+) -> None:
+    if snapshot.available:
+        return
+    reason = snapshot.unavailable_reason or "unknown git status failure"
+    raise ValidationFailed(f"{operation} requires Git change tracking: {reason}")
+
+
+def validate_reported_changes(
+    workspace: Workspace,
+    reported_changed_files: tuple[Path, ...],
+) -> None:
+    almanac_root = workspace.almanac_path.resolve()
+    for changed_file in reported_changed_files:
+        candidate = changed_file
+        if not candidate.is_absolute():
+            candidate = workspace.root_path / candidate
+        try:
+            candidate.resolve().relative_to(almanac_root)
+        except ValueError as error:
+            raise ValidationFailed(
+                "harness reported change outside configured Almanac root: "
+                f"{changed_file}"
+            ) from error
+
+
+def changed_paths(
+    before: WorkspaceChangeSnapshot,
+    after: WorkspaceChangeSnapshot,
+) -> tuple[Path, ...]:
+    before_by_path = changes_by_path(before.changes)
+    after_by_path = changes_by_path(after.changes)
+    paths = set(before_by_path) | set(after_by_path)
+    changed = [
+        path
+        for path in paths
+        if change_identity(before_by_path.get(path))
+        != change_identity(after_by_path.get(path))
+    ]
+    return tuple(sorted(changed, key=lambda item: item.as_posix()))
+
+
+def changes_by_path(
+    changes: tuple[WorkspacePathChange, ...],
+) -> dict[Path, WorkspacePathChange]:
+    return {change.path: change for change in changes}
+
+
+def change_identity(
+    change: WorkspacePathChange | None,
+) -> tuple[str, str, str | None] | None:
+    if change is None:
+        return None
+    return (change.state.value, change.status, change.fingerprint)
+
+
+def almanac_relative_path(workspace: Workspace) -> Path:
+    try:
+        return workspace.almanac_path.resolve().relative_to(
+            workspace.root_path.resolve()
+        )
+    except ValueError as error:
+        raise ValidationFailed(
+            f"Almanac root is outside workspace: {workspace.almanac_path}"
+        ) from error
+
+
+def path_is_under(path: Path, parent: Path) -> bool:
+    return path == parent or parent in path.parents
+
+
+def format_paths(paths: tuple[Path, ...]) -> str:
+    return ", ".join(path.as_posix() for path in paths)

codealmanac/workflows/sync/__init__.py

@@ -0,0 +1,3 @@
+from codealmanac.workflows.sync.service import SyncWorkflow
+
+__all__ = ["SyncWorkflow"]

codealmanac/workflows/sync/models.py

@@ -0,0 +1,157 @@
+from datetime import datetime
+from enum import StrEnum
+from pathlib import Path
+
+from pydantic import field_validator
+
+from codealmanac.core.models import CodeAlmanacModel
+from codealmanac.core.text import required_text
+from codealmanac.services.sources.models import TranscriptApp, TranscriptCandidate
+
+
+class SyncMode(StrEnum):
+    STATUS = "status"
+    SYNC = "sync"
+
+
+class SyncLedgerStatus(StrEnum):
+    DONE = "done"
+    PENDING = "pending"
+    FAILED = "failed"
+    NEEDS_ATTENTION = "needs_attention"
+
+
+class SyncDecisionKind(StrEnum):
+    SKIP = "skip"
+    NEEDS_ATTENTION = "needs_attention"
+    READY = "ready"
+
+
+class SyncLedgerEntry(CodeAlmanacModel):
+    app: TranscriptApp
+    session_id: str
+    transcript_path: Path
+    status: SyncLedgerStatus
+    last_absorbed_size: int
+    last_absorbed_line: int
+    last_absorbed_prefix_hash: str
+    last_absorbed_at: datetime | None = None
+    last_job_id: str | None = None
+    last_error: str | None = None
+    failed_attempts: int = 0
+    pending_started_at: datetime | None = None
+    pending_owner: str | None = None
+    pending_run_id: str | None = None
+    pending_to_size: int | None = None
+    pending_prefix_hash: str | None = None
+    pending_from_line: int | None = None
+    pending_to_line: int | None = None
+
+    @field_validator("session_id", "last_absorbed_prefix_hash")
+    @classmethod
+    def require_text(cls, value: str) -> str:
+        return required_text(value, "sync ledger entry")
+
+    @field_validator("pending_owner", "pending_run_id", "pending_prefix_hash")
+    @classmethod
+    def require_optional_pending_text(cls, value: str | None) -> str | None:
+        if value is None:
+            return None
+        return required_text(value, "sync pending value")
+
+    @field_validator("last_absorbed_size", "last_absorbed_line")
+    @classmethod
+    def non_negative_cursor(cls, value: int) -> int:
+        if value < 0:
+            raise ValueError("sync cursor must be non-negative")
+        return value
+
+    @field_validator("failed_attempts")
+    @classmethod
+    def non_negative_failed_attempts(cls, value: int) -> int:
+        if value < 0:
+            raise ValueError("sync failed attempts must be non-negative")
+        return value
+
+    @field_validator("pending_to_size", "pending_from_line", "pending_to_line")
+    @classmethod
+    def non_negative_pending_cursor(cls, value: int | None) -> int | None:
+        if value is not None and value < 0:
+            raise ValueError("sync pending cursor must be non-negative")
+        return value
+
+
+class SyncLedger(CodeAlmanacModel):
+    version: int
+    updated_at: datetime
+    sessions: dict[str, SyncLedgerEntry]
+
+
+class SyncReady(CodeAlmanacModel):
+    app: TranscriptApp
+    session_id: str
+    transcript_path: Path
+    repo_root: Path
+    from_line: int
+    to_line: int
+
+
+class SyncStarted(CodeAlmanacModel):
+    app: TranscriptApp
+    session_id: str
+    transcript_path: Path
+    repo_root: Path
+    run_id: str
+    from_line: int
+    to_line: int
+
+
+class SyncSkipped(CodeAlmanacModel):
+    transcript_path: Path
+    reason: str
+    app: TranscriptApp | None = None
+    session_id: str | None = None
+    repo_root: Path | None = None
+
+    @field_validator("reason")
+    @classmethod
+    def require_reason(cls, value: str) -> str:
+        return required_text(value, "sync skip reason")
+
+
+class SyncSummary(CodeAlmanacModel):
+    mode: SyncMode
+    scanned: int
+    eligible: int
+    ready: tuple[SyncReady, ...] = ()
+    started: tuple[SyncStarted, ...] = ()
+    skipped: tuple[SyncSkipped, ...] = ()
+    needs_attention: tuple[SyncSkipped, ...] = ()
+
+
+class TranscriptSnapshot(CodeAlmanacModel):
+    content: bytes
+    current_size: int
+    current_line: int
+
+
+class SyncCursorDecision(CodeAlmanacModel):
+    kind: SyncDecisionKind
+    reason: str = ""
+    from_line: int = 0
+    to_line: int = 0
+
+
+class SyncWorkItem(CodeAlmanacModel):
+    candidate: TranscriptCandidate
+    ledger_key: str
+    entry: SyncLedgerEntry
+    snapshot: TranscriptSnapshot
+    from_line: int
+    to_line: int
+
+
+class SyncEvaluation(CodeAlmanacModel):
+    summary: SyncSummary
+    work_items: tuple[SyncWorkItem, ...]
+    ledgers: dict[Path, SyncLedger]

codealmanac/workflows/sync/requests.py

@@ -0,0 +1,63 @@
+from datetime import datetime, timedelta
+from pathlib import Path
+
+from pydantic import field_validator
+
+from codealmanac.core.models import CodeAlmanacModel
+from codealmanac.core.text import required_text
+from codealmanac.services.harnesses.models import HarnessKind
+from codealmanac.services.sources.models import TranscriptApp
+
+DEFAULT_SYNC_PENDING_TIMEOUT = timedelta(hours=24)
+DEFAULT_SYNC_MAX_FAILED_ATTEMPTS = 3
+
+
+class SyncSelectionRequest(CodeAlmanacModel):
+    cwd: Path
+    apps: tuple[TranscriptApp, ...]
+    quiet: timedelta
+    wiki: str | None = None
+    home: Path | None = None
+    now: datetime | None = None
+    pending_timeout: timedelta = DEFAULT_SYNC_PENDING_TIMEOUT
+    max_failed_attempts: int = DEFAULT_SYNC_MAX_FAILED_ATTEMPTS
+
+    @field_validator("apps")
+    @classmethod
+    def require_apps(
+        cls,
+        value: tuple[TranscriptApp, ...],
+    ) -> tuple[TranscriptApp, ...]:
+        if len(value) == 0:
+            raise ValueError("at least one sync app is required")
+        return value
+
+    @field_validator("quiet", "pending_timeout")
+    @classmethod
+    def non_negative_duration(cls, value: timedelta) -> timedelta:
+        if value.total_seconds() < 0:
+            raise ValueError("sync duration must be non-negative")
+        return value
+
+    @field_validator("max_failed_attempts")
+    @classmethod
+    def non_negative_max_failed_attempts(cls, value: int) -> int:
+        if value < 0:
+            raise ValueError("sync max failed attempts must be non-negative")
+        return value
+
+
+class RunSyncStatusRequest(SyncSelectionRequest):
+    pass
+
+
+class RunSyncRequest(SyncSelectionRequest):
+    harness: HarnessKind
+    claim_owner: str | None = None
+
+    @field_validator("claim_owner")
+    @classmethod
+    def require_claim_owner(cls, value: str | None) -> str | None:
+        if value is None:
+            return None
+        return required_text(value, "sync claim owner")