codealmanac 0.1.0.dev0__py3-none-any.whl

codealmanac/services/runs/requests.py

@@ -0,0 +1,76 @@
+from pathlib import Path
+
+from pydantic import field_validator
+
+from codealmanac.core.models import CodeAlmanacModel
+from codealmanac.services.harnesses.models import HarnessTranscriptRef
+from codealmanac.services.runs.models import RunEventKind, RunOperation, RunStatus
+
+
+class ListRunsRequest(CodeAlmanacModel):
+    cwd: Path
+    wiki: str | None = None
+    limit: int | None = None
+
+    @field_validator("limit")
+    @classmethod
+    def non_negative_limit(cls, value: int | None) -> int | None:
+        if value is not None and value < 0:
+            raise ValueError("limit must be non-negative")
+        return value
+
+
+class ShowRunRequest(CodeAlmanacModel):
+    cwd: Path
+    run_id: str
+    wiki: str | None = None
+
+
+class ReadRunLogRequest(CodeAlmanacModel):
+    cwd: Path
+    run_id: str
+    wiki: str | None = None
+
+
+class StartRunRequest(CodeAlmanacModel):
+    cwd: Path
+    operation: RunOperation
+    wiki: str | None = None
+    title: str | None = None
+
+
+class RecordRunEventRequest(CodeAlmanacModel):
+    cwd: Path
+    run_id: str
+    kind: RunEventKind
+    message: str
+    wiki: str | None = None
+
+
+class MarkRunRunningRequest(CodeAlmanacModel):
+    cwd: Path
+    run_id: str
+    wiki: str | None = None
+
+
+class RecordRunHarnessTranscriptRequest(CodeAlmanacModel):
+    cwd: Path
+    run_id: str
+    transcript: HarnessTranscriptRef
+    wiki: str | None = None
+
+
+class FinishRunRequest(CodeAlmanacModel):
+    cwd: Path
+    run_id: str
+    status: RunStatus
+    wiki: str | None = None
+    summary: str | None = None
+    error: str | None = None
+
+    @field_validator("status")
+    @classmethod
+    def terminal_status(cls, value: RunStatus) -> RunStatus:
+        if value not in {RunStatus.DONE, RunStatus.FAILED, RunStatus.CANCELLED}:
+            raise ValueError("finish status must be done, failed, or cancelled")
+        return value

codealmanac/services/runs/service.py

@@ -0,0 +1,86 @@
+from pathlib import Path
+
+from codealmanac.services.runs.models import RunLogEvent, RunRecord
+from codealmanac.services.runs.requests import (
+    FinishRunRequest,
+    ListRunsRequest,
+    MarkRunRunningRequest,
+    ReadRunLogRequest,
+    RecordRunEventRequest,
+    RecordRunHarnessTranscriptRequest,
+    ShowRunRequest,
+    StartRunRequest,
+)
+from codealmanac.services.runs.store import RunStore
+from codealmanac.services.workspaces.models import Workspace
+from codealmanac.services.workspaces.requests import SelectWorkspaceRequest
+from codealmanac.services.workspaces.service import WorkspacesService
+
+
+class RunsService:
+    def __init__(self, workspaces: WorkspacesService, store: RunStore):
+        self.workspaces = workspaces
+        self.store = store
+
+    def start(self, request: StartRunRequest) -> RunRecord:
+        workspace = self.resolve_workspace(request.cwd, request.wiki)
+        return self.store.create(
+            workspace.almanac_path,
+            workspace.almanac_root,
+            workspace.workspace_id,
+            request.operation,
+            request.title,
+        )
+
+    def list(self, request: ListRunsRequest) -> tuple[RunRecord, ...]:
+        workspace = self.resolve_workspace(request.cwd, request.wiki)
+        return self.store.list(workspace.almanac_path, request.limit)
+
+    def show(self, request: ShowRunRequest) -> RunRecord:
+        workspace = self.resolve_workspace(request.cwd, request.wiki)
+        return self.store.read(workspace.almanac_path, request.run_id)
+
+    def log(self, request: ReadRunLogRequest) -> tuple[RunLogEvent, ...]:
+        workspace = self.resolve_workspace(request.cwd, request.wiki)
+        return self.store.log(workspace.almanac_path, request.run_id)
+
+    def record_event(self, request: RecordRunEventRequest) -> RunLogEvent:
+        workspace = self.resolve_workspace(request.cwd, request.wiki)
+        return self.store.append(
+            workspace.almanac_path,
+            request.run_id,
+            request.kind,
+            request.message,
+        )
+
+    def mark_running(self, request: MarkRunRunningRequest) -> RunRecord:
+        workspace = self.resolve_workspace(request.cwd, request.wiki)
+        return self.store.mark_running(workspace.almanac_path, request.run_id)
+
+    def record_harness_transcript(
+        self,
+        request: RecordRunHarnessTranscriptRequest,
+    ) -> RunRecord:
+        workspace = self.resolve_workspace(request.cwd, request.wiki)
+        return self.store.record_harness_transcript(
+            workspace.almanac_path,
+            request.run_id,
+            request.transcript,
+        )
+
+    def finish(self, request: FinishRunRequest) -> RunRecord:
+        workspace = self.resolve_workspace(request.cwd, request.wiki)
+        return self.store.finish(
+            workspace.almanac_path,
+            request.run_id,
+            request.status,
+            request.summary,
+            request.error,
+        )
+
+    def resolve_workspace(self, cwd: Path, wiki: str | None) -> Workspace:
+        if wiki is None:
+            return self.workspaces.resolve(cwd)
+        return self.workspaces.select(
+            SelectWorkspaceRequest(selector=wiki, base_path=cwd)
+        )

codealmanac/services/runs/store.py

@@ -0,0 +1,256 @@
+from datetime import UTC, datetime
+from pathlib import Path
+from uuid import uuid4
+
+from pydantic import ValidationError
+
+from codealmanac.core.errors import ConflictError, NotFoundError
+from codealmanac.services.harnesses.models import HarnessTranscriptRef
+from codealmanac.services.runs.models import (
+    RunEventKind,
+    RunLogEvent,
+    RunOperation,
+    RunRecord,
+    RunStatus,
+)
+
+
+class RunStore:
+    def create(
+        self,
+        almanac_path: Path,
+        almanac_root: Path,
+        workspace_id: str,
+        operation: RunOperation,
+        title: str | None,
+    ) -> RunRecord:
+        now = datetime.now(UTC)
+        run_id = new_run_id(operation, now)
+        record = RunRecord(
+            run_id=run_id,
+            workspace_id=workspace_id,
+            operation=operation,
+            status=RunStatus.QUEUED,
+            title=title,
+            created_at=now,
+            updated_at=now,
+            log_path=run_log_reference_path(almanac_root, run_id),
+        )
+        write_record(almanac_path, record)
+        append_event(
+            almanac_path,
+            RunLogEvent(
+                run_id=run_id,
+                sequence=1,
+                timestamp=now,
+                kind=RunEventKind.STATUS,
+                message=f"queued {operation.value}",
+            ),
+        )
+        return record
+
+    def list(self, almanac_path: Path, limit: int | None) -> tuple[RunRecord, ...]:
+        records = sorted(
+            iter_records(almanac_path),
+            key=lambda record: (record.created_at, record.run_id),
+            reverse=True,
+        )
+        if limit is not None:
+            return tuple(records[:limit])
+        return tuple(records)
+
+    def read(self, almanac_path: Path, run_id: str) -> RunRecord:
+        record = read_record(almanac_path, run_id)
+        if record is None:
+            raise NotFoundError("run", run_id)
+        return record
+
+    def log(self, almanac_path: Path, run_id: str) -> tuple[RunLogEvent, ...]:
+        self.read(almanac_path, run_id)
+        return tuple(iter_events(almanac_path, run_id))
+
+    def append(
+        self,
+        almanac_path: Path,
+        run_id: str,
+        kind: RunEventKind,
+        message: str,
+    ) -> RunLogEvent:
+        record = self.read(almanac_path, run_id)
+        event = RunLogEvent(
+            run_id=run_id,
+            sequence=next_sequence(almanac_path, run_id),
+            timestamp=datetime.now(UTC),
+            kind=kind,
+            message=message,
+        )
+        append_event(almanac_path, event)
+        write_record(
+            almanac_path,
+            record.model_copy(update={"updated_at": event.timestamp}),
+        )
+        return event
+
+    def mark_running(self, almanac_path: Path, run_id: str) -> RunRecord:
+        record = self.read(almanac_path, run_id)
+        if record.status == RunStatus.RUNNING:
+            return record
+        if record.status != RunStatus.QUEUED:
+            raise ConflictError(
+                f"run {run_id} cannot start from {record.status.value}"
+            )
+        now = datetime.now(UTC)
+        running = record.model_copy(
+            update={
+                "status": RunStatus.RUNNING,
+                "updated_at": now,
+                "started_at": now,
+            }
+        )
+        write_record(almanac_path, running)
+        append_event(
+            almanac_path,
+            RunLogEvent(
+                run_id=run_id,
+                sequence=next_sequence(almanac_path, run_id),
+                timestamp=now,
+                kind=RunEventKind.STATUS,
+                message=RunStatus.RUNNING.value,
+            ),
+        )
+        return running
+
+    def record_harness_transcript(
+        self,
+        almanac_path: Path,
+        run_id: str,
+        transcript: HarnessTranscriptRef,
+    ) -> RunRecord:
+        record = self.read(almanac_path, run_id)
+        updated = record.model_copy(
+            update={
+                "harness_transcript": transcript,
+                "updated_at": datetime.now(UTC),
+            }
+        )
+        write_record(almanac_path, updated)
+        return updated
+
+    def finish(
+        self,
+        almanac_path: Path,
+        run_id: str,
+        status: RunStatus,
+        summary: str | None,
+        error: str | None,
+    ) -> RunRecord:
+        record = self.read(almanac_path, run_id)
+        now = datetime.now(UTC)
+        finished = record.model_copy(
+            update={
+                "status": status,
+                "summary": summary,
+                "error": error,
+                "updated_at": now,
+                "finished_at": now,
+            }
+        )
+        write_record(almanac_path, finished)
+        append_event(
+            almanac_path,
+            RunLogEvent(
+                run_id=run_id,
+                sequence=next_sequence(almanac_path, run_id),
+                timestamp=now,
+                kind=RunEventKind.STATUS,
+                message=status.value,
+            ),
+        )
+        return finished
+
+
+def new_run_id(operation: RunOperation, now: datetime) -> str:
+    stamp = now.strftime("%Y%m%d%H%M%S")
+    return f"{operation.value}-{stamp}-{uuid4().hex[:8]}"
+
+
+def runs_dir(almanac_path: Path) -> Path:
+    return almanac_path / "jobs"
+
+
+def run_record_path(almanac_path: Path, run_id: str) -> Path:
+    return runs_dir(almanac_path) / f"{run_id}.json"
+
+
+def run_log_path(almanac_path: Path, run_id: str) -> Path:
+    return runs_dir(almanac_path) / f"{run_id}.jsonl"
+
+
+def run_log_reference_path(almanac_root: Path, run_id: str) -> Path:
+    return almanac_root / "jobs" / f"{run_id}.jsonl"
+
+
+def write_record(almanac_path: Path, record: RunRecord) -> None:
+    path = run_record_path(almanac_path, record.run_id)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary = path.with_name(f".{path.name}.{uuid4().hex}.tmp")
+    try:
+        temporary.write_text(record.model_dump_json(indent=2), encoding="utf-8")
+        temporary.replace(path)
+    finally:
+        if temporary.exists():
+            temporary.unlink()
+
+
+def read_record(almanac_path: Path, run_id: str) -> RunRecord | None:
+    path = run_record_path(almanac_path, run_id)
+    if not path.is_file():
+        return None
+    try:
+        return RunRecord.model_validate_json(path.read_text(encoding="utf-8"))
+    except (OSError, ValidationError, ValueError):
+        return None
+
+
+def iter_records(almanac_path: Path) -> tuple[RunRecord, ...]:
+    directory = runs_dir(almanac_path)
+    if not directory.is_dir():
+        return ()
+    records: list[RunRecord] = []
+    for path in sorted(directory.glob("*.json")):
+        run_id = path.stem
+        record = read_record(almanac_path, run_id)
+        if record is not None:
+            records.append(record)
+    return tuple(records)
+
+
+def append_event(almanac_path: Path, event: RunLogEvent) -> None:
+    path = run_log_path(almanac_path, event.run_id)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("a", encoding="utf-8") as file:
+        file.write(event.model_dump_json())
+        file.write("\n")
+
+
+def iter_events(almanac_path: Path, run_id: str) -> tuple[RunLogEvent, ...]:
+    path = run_log_path(almanac_path, run_id)
+    if not path.is_file():
+        return ()
+    try:
+        lines = path.read_text(encoding="utf-8").splitlines()
+    except OSError:
+        return ()
+    events: list[RunLogEvent] = []
+    for line in lines:
+        if not line.strip():
+            continue
+        try:
+            events.append(RunLogEvent.model_validate_json(line))
+        except (ValidationError, ValueError):
+            continue
+    return tuple(events)
+
+
+def next_sequence(almanac_path: Path, run_id: str) -> int:
+    return len(iter_events(almanac_path, run_id)) + 1

codealmanac/services/search/__init__.py

@@ -0,0 +1 @@
+

codealmanac/services/search/requests.py

@@ -0,0 +1,23 @@
+from pathlib import Path
+
+from pydantic import field_validator
+
+from codealmanac.core.models import CodeAlmanacModel
+
+
+class SearchPagesRequest(CodeAlmanacModel):
+    cwd: Path
+    wiki: str | None = None
+    query: str | None = None
+    topics: tuple[str, ...] = ()
+    mentions: str | None = None
+    include_archive: bool = False
+    archived: bool = False
+    limit: int | None = None
+
+    @field_validator("limit")
+    @classmethod
+    def non_negative_limit(cls, value: int | None) -> int | None:
+        if value is not None and value < 0:
+            raise ValueError("limit must be non-negative")
+        return value

codealmanac/services/search/service.py

@@ -0,0 +1,31 @@
+from codealmanac.services.index.models import SearchPageResult
+from codealmanac.services.index.requests import SearchIndexRequest
+from codealmanac.services.index.service import IndexService
+from codealmanac.services.search.requests import SearchPagesRequest
+from codealmanac.services.workspaces.requests import SelectWorkspaceRequest
+from codealmanac.services.workspaces.service import WorkspacesService
+
+
+class SearchService:
+    def __init__(self, workspaces: WorkspacesService, index: IndexService):
+        self.workspaces = workspaces
+        self.index = index
+
+    def search(self, request: SearchPagesRequest) -> tuple[SearchPageResult, ...]:
+        if request.wiki is None:
+            workspace = self.workspaces.resolve(request.cwd)
+        else:
+            workspace = self.workspaces.select(
+                SelectWorkspaceRequest(selector=request.wiki, base_path=request.cwd)
+            )
+        return self.index.search(
+            workspace.workspace_id,
+            SearchIndexRequest(
+                query=request.query,
+                topics=request.topics,
+                mentions=request.mentions,
+                include_archive=request.include_archive,
+                archived=request.archived,
+                limit=request.limit,
+            ),
+        )

codealmanac/services/sources/__init__.py

@@ -0,0 +1 @@
+"""Source input contracts for lifecycle workflows."""

codealmanac/services/sources/models.py

@@ -0,0 +1,126 @@
+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
+
+
+class SourceKind(StrEnum):
+    PATH_FILE = "path.file"
+    PATH_DIRECTORY = "path.directory"
+    PATH_UNKNOWN = "path.unknown"
+    GITHUB_PULL_REQUEST = "github.pull_request"
+    GITHUB_ISSUE = "github.issue"
+    WEB_URL = "web.url"
+    GIT_RANGE = "git.range"
+    GIT_DIFF = "git.diff"
+    TRANSCRIPT = "transcript"
+
+
+class SourceProvenanceKind(StrEnum):
+    FILE = "file"
+    DIRECTORY = "directory"
+    MISSING_PATH = "missing_path"
+    PR = "pr"
+    ISSUE = "issue"
+    URL = "url"
+    GIT = "git"
+    TRANSCRIPT = "transcript"
+
+
+class SourceRuntimeStatus(StrEnum):
+    AVAILABLE = "available"
+    SKIPPED = "skipped"
+    UNAVAILABLE = "unavailable"
+
+
+class TranscriptApp(StrEnum):
+    CLAUDE = "claude"
+    CODEX = "codex"
+
+
+class SourceAddress(CodeAlmanacModel):
+    raw: str
+
+    @field_validator("raw")
+    @classmethod
+    def require_raw(cls, value: str) -> str:
+        return required_text(value, "source address")
+
+
+class SourceRef(CodeAlmanacModel):
+    raw: str
+    kind: SourceKind
+    identity: str
+    path: Path | None = None
+    url: str | None = None
+    repository: str | None = None
+    number: int | None = None
+    revision_range: str | None = None
+    transcript: str | None = None
+    exists: bool | None = None
+    fingerprint: str | None = None
+
+    @field_validator("raw", "identity")
+    @classmethod
+    def require_text_fields(cls, value: str) -> str:
+        return required_text(value, "source reference")
+
+    @field_validator("number")
+    @classmethod
+    def positive_number(cls, value: int | None) -> int | None:
+        if value is not None and value < 1:
+            raise ValueError("source number must be positive")
+        return value
+
+
+class SourceBrief(CodeAlmanacModel):
+    ref: SourceRef
+    title: str
+    provenance_kind: SourceProvenanceKind
+    prompt_hint: str
+
+    @field_validator("title", "prompt_hint")
+    @classmethod
+    def require_brief_text(cls, value: str) -> str:
+        return required_text(value, "source brief")
+
+
+class SourceRuntime(CodeAlmanacModel):
+    ref: SourceRef
+    status: SourceRuntimeStatus
+    title: str
+    content: str | None = None
+    diagnostics: tuple[str, ...] = ()
+    truncated: bool = False
+
+    @field_validator("title")
+    @classmethod
+    def require_title(cls, value: str) -> str:
+        return required_text(value, "source runtime title")
+
+
+class TranscriptCandidate(CodeAlmanacModel):
+    app: TranscriptApp
+    session_id: str
+    transcript_path: Path
+    cwd: Path
+    repo_root: Path
+    almanac_path: Path
+    modified_at: datetime
+    size_bytes: int
+
+    @field_validator("session_id")
+    @classmethod
+    def require_session_id(cls, value: str) -> str:
+        return required_text(value, "transcript session id")
+
+    @field_validator("size_bytes")
+    @classmethod
+    def non_negative_size(cls, value: int) -> int:
+        if value < 0:
+            raise ValueError("transcript size must be non-negative")
+        return value

codealmanac/services/sources/ports.py

@@ -0,0 +1,30 @@
+from typing import Protocol
+
+from codealmanac.services.sources.models import (
+    SourceRef,
+    SourceRuntime,
+    TranscriptApp,
+    TranscriptCandidate,
+)
+from codealmanac.services.sources.requests import (
+    DiscoverTranscriptsRequest,
+    InspectSourceRuntimeRequest,
+)
+
+
+class TranscriptDiscoveryAdapter(Protocol):
+    app: TranscriptApp
+
+    def discover(
+        self,
+        request: DiscoverTranscriptsRequest,
+    ) -> tuple[TranscriptCandidate, ...]:
+        """Return local transcript candidates for one supported agent app."""
+
+
+class SourceRuntimeAdapter(Protocol):
+    def supports(self, ref: SourceRef) -> bool:
+        """Return true when this adapter can inspect the source ref."""
+
+    def inspect(self, request: InspectSourceRuntimeRequest) -> SourceRuntime:
+        """Return bounded runtime material for one source ref."""