codealmanac 0.1.0.dev0__py3-none-any.whl

codealmanac/services/diagnostics/service.py

@@ -0,0 +1,283 @@
+import platform
+import sys
+from collections.abc import Sequence
+
+from codealmanac.core.errors import CodeAlmanacError, NotFoundError
+from codealmanac.manual import ManualLibrary
+from codealmanac.services.diagnostics.models import (
+    DoctorCheck,
+    DoctorReport,
+    DoctorStatus,
+)
+from codealmanac.services.diagnostics.requests import DoctorRequest
+from codealmanac.services.index.models import HealthReport, IndexSummary
+from codealmanac.services.index.service import IndexService
+from codealmanac.services.workspaces.models import Workspace, WorkspaceRegistryStatus
+from codealmanac.services.workspaces.requests import SelectWorkspaceRequest
+from codealmanac.services.workspaces.service import (
+    WorkspacesService,
+    workspace_registry_status,
+)
+
+
+class DiagnosticsService:
+    def __init__(
+        self,
+        workspaces: WorkspacesService,
+        index: IndexService,
+        manual: ManualLibrary,
+        version: str,
+        python_version: str | None = None,
+        python_supported: bool | None = None,
+    ):
+        self.workspaces = workspaces
+        self.index = index
+        self.manual = manual
+        self.version = version
+        self.python_version = python_version or platform.python_version()
+        if python_supported is None:
+            self.python_supported = sys.version_info >= (3, 12)
+        else:
+            self.python_supported = python_supported
+
+    def check(self, request: DoctorRequest) -> DoctorReport:
+        return DoctorReport(
+            version=self.version,
+            install=self._install_checks(),
+            wiki=self._wiki_checks(request),
+        )
+
+    def _install_checks(self) -> tuple[DoctorCheck, ...]:
+        return (
+            DoctorCheck(
+                key="install.version",
+                status=DoctorStatus.OK,
+                message=f"codealmanac {self.version}",
+            ),
+            DoctorCheck(
+                key="install.python",
+                status=(
+                    DoctorStatus.OK if self.python_supported else DoctorStatus.PROBLEM
+                ),
+                message=f"python {self.python_version}",
+                fix=None
+                if self.python_supported
+                else "install Python 3.12 or newer",
+            ),
+            DoctorCheck(
+                key="install.registry",
+                status=DoctorStatus.INFO,
+                message=f"registry: {self.workspaces.registry_path}",
+            ),
+            self._manual_package_check(),
+        )
+
+    def _wiki_checks(self, request: DoctorRequest) -> tuple[DoctorCheck, ...]:
+        workspace = self._select_workspace(request)
+        if isinstance(workspace, DoctorCheck):
+            return (workspace,)
+        registry_status = workspace_registry_status(workspace)
+        checks: list[DoctorCheck] = [
+            DoctorCheck(
+                key="wiki.repo",
+                status=DoctorStatus.INFO,
+                message=f"repo: {workspace.root_path}",
+            ),
+            registered_check(workspace, registry_status),
+        ]
+        if registry_status != WorkspaceRegistryStatus.AVAILABLE:
+            return tuple(checks)
+        checks.extend(self._index_checks(workspace))
+        checks.append(self._manual_workspace_check(workspace))
+        checks.append(self._health_check(workspace))
+        return tuple(checks)
+
+    def _manual_package_check(self) -> DoctorCheck:
+        try:
+            inventory = self.manual.inventory()
+        except CodeAlmanacError as error:
+            return DoctorCheck(
+                key="install.manual",
+                status=DoctorStatus.PROBLEM,
+                message=f"manual package unavailable: {first_line(str(error))}",
+                fix="reinstall codealmanac",
+            )
+        return DoctorCheck(
+            key="install.manual",
+            status=DoctorStatus.OK,
+            message=f"manual: {len(inventory.documents)} bundled docs",
+        )
+
+    def _manual_workspace_check(self, workspace: Workspace) -> DoctorCheck:
+        try:
+            status = self.manual.workspace_status(workspace.almanac_path / "manual")
+        except CodeAlmanacError as error:
+            return DoctorCheck(
+                key="wiki.manual",
+                status=DoctorStatus.PROBLEM,
+                message=f"manual unavailable: {first_line(str(error))}",
+                fix="run: codealmanac build",
+            )
+        if status.complete:
+            if len(status.changed) > 0:
+                changed = ", ".join(status.changed)
+                return DoctorCheck(
+                    key="wiki.manual",
+                    status=DoctorStatus.INFO,
+                    message=f"manual differs: {changed}",
+                    fix=(
+                        "review local manual files; "
+                        "codealmanac build preserves existing files"
+                    ),
+                )
+            return DoctorCheck(
+                key="wiki.manual",
+                status=DoctorStatus.OK,
+                message=f"manual: {len(status.present)} docs",
+            )
+        missing = ", ".join(status.missing)
+        return DoctorCheck(
+            key="wiki.manual",
+            status=DoctorStatus.PROBLEM,
+            message=f"manual missing: {missing}",
+            fix="run: codealmanac build",
+        )
+
+    def _select_workspace(self, request: DoctorRequest) -> Workspace | DoctorCheck:
+        try:
+            if request.wiki is None:
+                return self.workspaces.resolve(request.cwd)
+            return self.workspaces.select(
+                SelectWorkspaceRequest(selector=request.wiki, base_path=request.cwd)
+            )
+        except NotFoundError as error:
+            if request.wiki is None:
+                return DoctorCheck(
+                    key="wiki.none",
+                    status=DoctorStatus.INFO,
+                    message="no Almanac wiki found from current directory",
+                    fix="run: codealmanac init",
+                )
+            return DoctorCheck(
+                key="wiki.selected",
+                status=DoctorStatus.PROBLEM,
+                message=first_line(str(error)),
+                fix="run: codealmanac list",
+            )
+        except CodeAlmanacError as error:
+            return DoctorCheck(
+                key="wiki.selected",
+                status=DoctorStatus.PROBLEM,
+                message=first_line(str(error)),
+                fix="run: codealmanac list",
+            )
+
+    def _index_checks(self, workspace: Workspace) -> Sequence[DoctorCheck]:
+        try:
+            summary = self.index.summary(workspace.workspace_id)
+        except Exception as error:
+            return (
+                DoctorCheck(
+                    key="wiki.index",
+                    status=DoctorStatus.PROBLEM,
+                    message=f"could not rebuild index: {first_line(str(error))}",
+                    fix="run: codealmanac reindex",
+                ),
+            )
+        return (
+            DoctorCheck(
+                key="wiki.index",
+                status=DoctorStatus.OK,
+                message=index_message(summary),
+            ),
+        )
+
+    def _health_check(self, workspace: Workspace) -> DoctorCheck:
+        try:
+            report = self.index.health_report(workspace.workspace_id)
+        except Exception as error:
+            return DoctorCheck(
+                key="wiki.health",
+                status=DoctorStatus.PROBLEM,
+                message=f"could not run health: {first_line(str(error))}",
+                fix="run: codealmanac health",
+            )
+        problems = health_problem_count(report)
+        if problems == 0:
+            return DoctorCheck(
+                key="wiki.health",
+                status=DoctorStatus.OK,
+                message="health: 0 problems",
+            )
+        return DoctorCheck(
+            key="wiki.health",
+            status=DoctorStatus.PROBLEM,
+            message=f"health: {problems} {problem_word(problems)}",
+            fix="run: codealmanac health",
+        )
+
+
+def index_message(summary: IndexSummary) -> str:
+    skip_suffix = (
+        f", {summary.files_skipped} skipped" if summary.files_skipped > 0 else ""
+    )
+    return (
+        f"index: {summary.pages} {page_word(summary.pages)}, "
+        f"{summary.topics} {topic_word(summary.topics)} "
+        f"({summary.files_seen} files seen{skip_suffix})"
+    )
+
+
+def health_problem_count(report: HealthReport) -> int:
+    return (
+        len(report.orphans)
+        + len(report.dead_refs)
+        + len(report.broken_links)
+        + len(report.broken_xwiki)
+        + len(report.empty_topics)
+        + len(report.empty_pages)
+    )
+
+
+def first_line(value: str) -> str:
+    return value.splitlines()[0] if value.splitlines() else value
+
+
+def registered_check(
+    workspace: Workspace,
+    status: WorkspaceRegistryStatus,
+) -> DoctorCheck:
+    registered = (
+        f"registered as '{workspace.name}' ({workspace.almanac_root.as_posix()})"
+    )
+    if status == WorkspaceRegistryStatus.AVAILABLE:
+        return DoctorCheck(
+            key="wiki.registered",
+            status=DoctorStatus.OK,
+            message=registered,
+        )
+    if status == WorkspaceRegistryStatus.MISSING_REPO:
+        return DoctorCheck(
+            key="wiki.registered",
+            status=DoctorStatus.PROBLEM,
+            message=f"{registered}, but repo path is missing",
+            fix=f"run: codealmanac list --drop {workspace.workspace_id}",
+        )
+    return DoctorCheck(
+        key="wiki.registered",
+        status=DoctorStatus.PROBLEM,
+        message=f"{registered}, but Almanac root is missing: {workspace.almanac_path}",
+        fix="run: codealmanac build",
+    )
+
+
+def page_word(count: int) -> str:
+    return "page" if count == 1 else "pages"
+
+
+def topic_word(count: int) -> str:
+    return "topic" if count == 1 else "topics"
+
+
+def problem_word(count: int) -> str:
+    return "problem" if count == 1 else "problems"

codealmanac/services/harnesses/__init__.py

@@ -0,0 +1 @@
+"""Normalized AI harness contracts for lifecycle workflows."""

codealmanac/services/harnesses/models.py

@@ -0,0 +1,104 @@
+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 HarnessKind(StrEnum):
+    CODEX = "codex"
+    CLAUDE = "claude"
+
+
+class HarnessRunStatus(StrEnum):
+    SUCCEEDED = "succeeded"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+
+class HarnessEventKind(StrEnum):
+    TEXT = "text"
+    TOOL_USE = "tool_use"
+    TOOL_RESULT = "tool_result"
+    TOOL_SUMMARY = "tool_summary"
+    CONTEXT_USAGE = "context_usage"
+    WARNING = "warning"
+    ERROR = "error"
+    DONE = "done"
+
+
+class HarnessReadiness(CodeAlmanacModel):
+    kind: HarnessKind
+    available: bool
+    message: str
+
+    @field_validator("message")
+    @classmethod
+    def require_message(cls, value: str) -> str:
+        return required_text(value, "harness readiness message")
+
+
+class HarnessTranscriptRef(CodeAlmanacModel):
+    kind: HarnessKind
+    session_id: str
+    transcript_path: Path | None = None
+
+    @field_validator("session_id")
+    @classmethod
+    def require_session_id(cls, value: str) -> str:
+        return required_text(value, "harness transcript session id")
+
+
+class HarnessEvent(CodeAlmanacModel):
+    kind: HarnessEventKind
+    message: str
+    status: HarnessRunStatus | None = None
+
+    @field_validator("message")
+    @classmethod
+    def require_message(cls, value: str) -> str:
+        return required_text(value, "harness event message")
+
+
+class HarnessRunResult(CodeAlmanacModel):
+    kind: HarnessKind
+    status: HarnessRunStatus
+    output_text: str
+    summary: str | None = None
+    changed_files: tuple[Path, ...] = ()
+    transcript: HarnessTranscriptRef | None = None
+    events: tuple[HarnessEvent, ...] = ()
+
+    @field_validator("output_text")
+    @classmethod
+    def require_output_text(cls, value: str) -> str:
+        return required_text(value, "harness output")
+
+
+def terminal_harness_event(
+    kind: HarnessKind,
+    status: HarnessRunStatus,
+    output_text: str,
+) -> HarnessEvent:
+    return HarnessEvent(
+        kind=HarnessEventKind.DONE,
+        status=status,
+        message=terminal_harness_message(kind, status, output_text),
+    )
+
+
+def terminal_harness_message(
+    kind: HarnessKind,
+    status: HarnessRunStatus,
+    output_text: str,
+) -> str:
+    suffix = first_line(output_text)
+    details = f": {suffix}" if suffix else ""
+    return f"{kind.value} {status.value}{details}"
+
+
+def first_line(value: str) -> str:
+    lines = value.splitlines()
+    return lines[0] if lines else value

codealmanac/services/harnesses/ports.py

@@ -0,0 +1,18 @@
+from typing import Protocol
+
+from codealmanac.services.harnesses.models import (
+    HarnessKind,
+    HarnessReadiness,
+    HarnessRunResult,
+)
+from codealmanac.services.harnesses.requests import RunHarnessRequest
+
+
+class HarnessAdapter(Protocol):
+    kind: HarnessKind
+
+    def check(self) -> HarnessReadiness:
+        """Return local readiness without starting an agent run."""
+
+    def run(self, request: RunHarnessRequest) -> HarnessRunResult:
+        """Run one normalized agent task."""

codealmanac/services/harnesses/requests.py

@@ -0,0 +1,19 @@
+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
+
+
+class RunHarnessRequest(CodeAlmanacModel):
+    kind: HarnessKind
+    cwd: Path
+    prompt: str
+    title: str | None = None
+
+    @field_validator("prompt")
+    @classmethod
+    def require_prompt(cls, value: str) -> str:
+        return required_text(value, "harness prompt")

codealmanac/services/harnesses/service.py

@@ -0,0 +1,38 @@
+from collections.abc import Sequence
+
+from codealmanac.core.errors import ConflictError, NotFoundError
+from codealmanac.services.harnesses.models import (
+    HarnessKind,
+    HarnessReadiness,
+    HarnessRunResult,
+)
+from codealmanac.services.harnesses.ports import HarnessAdapter
+from codealmanac.services.harnesses.requests import RunHarnessRequest
+
+
+class HarnessesService:
+    def __init__(self, adapters: Sequence[HarnessAdapter] = ()):
+        self.adapters = adapters_by_kind(adapters)
+
+    def check(self) -> tuple[HarnessReadiness, ...]:
+        return tuple(adapter.check() for adapter in self.adapters.values())
+
+    def run(self, request: RunHarnessRequest) -> HarnessRunResult:
+        return self.adapter_for(request.kind).run(request)
+
+    def adapter_for(self, kind: HarnessKind) -> HarnessAdapter:
+        try:
+            return self.adapters[kind]
+        except KeyError as error:
+            raise NotFoundError("harness", kind.value) from error
+
+
+def adapters_by_kind(
+    adapters: Sequence[HarnessAdapter],
+) -> dict[HarnessKind, HarnessAdapter]:
+    indexed: dict[HarnessKind, HarnessAdapter] = {}
+    for adapter in adapters:
+        if adapter.kind in indexed:
+            raise ConflictError(f"duplicate harness adapter: {adapter.kind.value}")
+        indexed[adapter.kind] = adapter
+    return indexed

codealmanac/services/health/__init__.py

@@ -0,0 +1 @@
+

codealmanac/services/health/requests.py

@@ -0,0 +1,8 @@
+from pathlib import Path
+
+from codealmanac.core.models import CodeAlmanacModel
+
+
+class HealthCheckRequest(CodeAlmanacModel):
+    cwd: Path
+    wiki: str | None = None

codealmanac/services/health/service.py

@@ -0,0 +1,20 @@
+from codealmanac.services.health.requests import HealthCheckRequest
+from codealmanac.services.index.models import HealthReport
+from codealmanac.services.index.service import IndexService
+from codealmanac.services.workspaces.requests import SelectWorkspaceRequest
+from codealmanac.services.workspaces.service import WorkspacesService
+
+
+class HealthService:
+    def __init__(self, workspaces: WorkspacesService, index: IndexService):
+        self.workspaces = workspaces
+        self.index = index
+
+    def check(self, request: HealthCheckRequest) -> HealthReport:
+        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.health_report(workspace.workspace_id)

codealmanac/services/index/__init__.py

@@ -0,0 +1 @@
+

codealmanac/services/index/models.py

@@ -0,0 +1,135 @@
+from enum import StrEnum
+from pathlib import Path
+
+from codealmanac.core.models import CodeAlmanacModel
+
+
+class HealthCategory(StrEnum):
+    ORPHANS = "orphans"
+    DEAD_REFS = "dead_refs"
+    BROKEN_LINKS = "broken_links"
+    BROKEN_XWIKI = "broken_xwiki"
+    EMPTY_TOPICS = "empty_topics"
+    EMPTY_PAGES = "empty_pages"
+
+
+class SearchPageResult(CodeAlmanacModel):
+    slug: str
+    title: str | None
+    summary: str | None
+    updated_at: int
+    archived_at: int | None
+    superseded_by: str | None
+    topics: tuple[str, ...]
+
+
+class PageFileReference(CodeAlmanacModel):
+    path: str
+    is_dir: bool
+
+
+class CrossWikiReference(CodeAlmanacModel):
+    wiki: str
+    target: str
+
+
+class PageView(CodeAlmanacModel):
+    slug: str
+    title: str | None
+    summary: str | None
+    file_path: Path
+    updated_at: int
+    archived_at: int | None
+    superseded_by: str | None
+    topics: tuple[str, ...]
+    file_refs: tuple[PageFileReference, ...]
+    wikilinks_out: tuple[str, ...]
+    wikilinks_in: tuple[str, ...]
+    cross_wiki_links: tuple[CrossWikiReference, ...]
+    body: str
+
+
+class IndexRefreshResult(CodeAlmanacModel):
+    changed: int
+    removed: int
+    pages_indexed: int
+    files_seen: int
+    files_skipped: int
+
+
+class IndexCounts(CodeAlmanacModel):
+    pages: int
+    topics: int
+
+
+class IndexSummary(CodeAlmanacModel):
+    pages: int
+    topics: int
+    files_seen: int
+    files_skipped: int
+
+
+class IndexedPageFingerprint(CodeAlmanacModel):
+    slug: str
+    relative_path: str
+    content_hash: str
+
+
+class IndexSourceSignature(CodeAlmanacModel):
+    pages: tuple[IndexedPageFingerprint, ...]
+    topics_hash: str
+    files_seen: int
+    files_skipped: int
+
+
+class TopicSummary(CodeAlmanacModel):
+    slug: str
+    title: str | None
+    description: str | None
+    page_count: int
+
+
+class TopicDetail(CodeAlmanacModel):
+    slug: str
+    title: str | None
+    description: str | None
+    parents: tuple[str, ...]
+    children: tuple[str, ...]
+    pages: tuple[str, ...]
+
+
+class OrphanPage(CodeAlmanacModel):
+    slug: str
+
+
+class DeadFileReference(CodeAlmanacModel):
+    slug: str
+    path: str
+
+
+class BrokenPageLink(CodeAlmanacModel):
+    source_slug: str
+    target_slug: str
+
+
+class BrokenCrossWikiLink(CodeAlmanacModel):
+    source_slug: str
+    target_wiki: str
+    target_slug: str
+
+
+class EmptyTopic(CodeAlmanacModel):
+    slug: str
+
+
+class EmptyPage(CodeAlmanacModel):
+    slug: str
+
+
+class HealthReport(CodeAlmanacModel):
+    orphans: tuple[OrphanPage, ...]
+    dead_refs: tuple[DeadFileReference, ...]
+    broken_links: tuple[BrokenPageLink, ...]
+    broken_xwiki: tuple[BrokenCrossWikiLink, ...]
+    empty_topics: tuple[EmptyTopic, ...]
+    empty_pages: tuple[EmptyPage, ...]

codealmanac/services/index/requests.py

@@ -0,0 +1,26 @@
+from pathlib import Path
+
+from pydantic import field_validator
+
+from codealmanac.core.models import CodeAlmanacModel
+
+
+class SearchIndexRequest(CodeAlmanacModel):
+    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
+
+
+class ReindexRequest(CodeAlmanacModel):
+    cwd: Path
+    wiki: str | None = None