codealmanac 0.1.0.dev0__py3-none-any.whl

codealmanac/services/workspaces/requests.py

@@ -0,0 +1,82 @@
+from pathlib import Path
+
+from pydantic import Field, field_validator
+
+from codealmanac.core.models import CodeAlmanacModel
+from codealmanac.core.text import required_text
+from codealmanac.services.workspaces.roots import (
+    DEFAULT_ALMANAC_ROOT,
+    validate_almanac_root_field,
+)
+
+
+class RegisterWorkspaceRequest(CodeAlmanacModel):
+    root_path: Path
+    almanac_root: Path = Field(default=DEFAULT_ALMANAC_ROOT)
+    name: str | None = Field(
+        default=None,
+        description="None means derive the registry name from the root path.",
+    )
+    description: str = ""
+
+    @field_validator("name")
+    @classmethod
+    def require_name(cls, value: str | None) -> str | None:
+        if value is None:
+            return None
+        return required_text(value, "workspace name")
+
+    @field_validator("almanac_root")
+    @classmethod
+    def validate_almanac_root(cls, value: Path) -> Path:
+        return validate_almanac_root_field(value)
+
+
+class InitializeWorkspaceRequest(CodeAlmanacModel):
+    path: Path
+    almanac_root: Path | None = None
+    name: str | None = Field(
+        default=None,
+        description="None means derive the registry name from the workspace path.",
+    )
+    description: str = ""
+
+    @field_validator("name")
+    @classmethod
+    def require_name(cls, value: str | None) -> str | None:
+        if value is None:
+            return None
+        return required_text(value, "workspace name")
+
+    @field_validator("almanac_root")
+    @classmethod
+    def validate_almanac_root(cls, value: Path | None) -> Path | None:
+        if value is None:
+            return None
+        return validate_almanac_root_field(value)
+
+
+class SelectWorkspaceRequest(CodeAlmanacModel):
+    selector: str
+    base_path: Path | None = Field(
+        default=None,
+        description="None means relative path selectors are not resolved.",
+    )
+
+    @field_validator("selector")
+    @classmethod
+    def require_selector(cls, value: str) -> str:
+        return required_text(value, "workspace selector")
+
+
+class DropWorkspaceRequest(CodeAlmanacModel):
+    selector: str
+    base_path: Path | None = Field(
+        default=None,
+        description="None means relative path selectors are not resolved.",
+    )
+
+    @field_validator("selector")
+    @classmethod
+    def require_selector(cls, value: str) -> str:
+        return required_text(value, "workspace selector")

codealmanac/services/workspaces/roots.py

@@ -0,0 +1,74 @@
+from collections.abc import Iterable
+from pathlib import Path
+
+from codealmanac.core.models import CodeAlmanacModel
+from codealmanac.core.paths import normalize_path
+
+DEFAULT_ALMANAC_ROOT = Path("almanac")
+ALMANAC_ROOT_MARKER_FILES = ("README.md", "topics.yaml")
+ALMANAC_ROOT_MARKER_DIRS = ("pages",)
+
+
+class AlmanacRootMatch(CodeAlmanacModel):
+    repo_root: Path
+    almanac_root: Path
+    almanac_path: Path
+
+
+def normalize_almanac_root(value: Path | str | None) -> Path:
+    if value is None:
+        return DEFAULT_ALMANAC_ROOT
+    path = Path(value)
+    if path.is_absolute():
+        raise ValueError("Almanac root must be a repo-relative path")
+    if len(path.parts) == 0:
+        raise ValueError("Almanac root must name a directory")
+    if any(part in {"..", "~"} for part in path.parts):
+        raise ValueError("Almanac root must stay inside the repo")
+    return Path(*path.parts)
+
+
+def normalized_almanac_roots(values: Iterable[Path | str]) -> tuple[Path, ...]:
+    roots: list[Path] = []
+    for value in values:
+        root = normalize_almanac_root(value)
+        if root not in roots:
+            roots.append(root)
+    if len(roots) == 0:
+        roots.append(DEFAULT_ALMANAC_ROOT)
+    return tuple(roots)
+
+
+def nearest_almanac_root(
+    path: Path,
+    almanac_roots: Iterable[Path | str] = (DEFAULT_ALMANAC_ROOT,),
+) -> AlmanacRootMatch | None:
+    current = normalize_path(path)
+    if current.is_file():
+        current = current.parent
+    roots = normalized_almanac_roots(almanac_roots)
+    for candidate in [current, *current.parents]:
+        for almanac_root in roots:
+            almanac_path = candidate / almanac_root
+            if is_initialized_almanac_root(almanac_path):
+                return AlmanacRootMatch(
+                    repo_root=candidate,
+                    almanac_root=almanac_root,
+                    almanac_path=normalize_path(almanac_path),
+                )
+    return None
+
+
+def is_initialized_almanac_root(path: Path) -> bool:
+    if not path.is_dir():
+        return False
+    if any((path / name).is_file() for name in ALMANAC_ROOT_MARKER_FILES):
+        return True
+    return any((path / name).is_dir() for name in ALMANAC_ROOT_MARKER_DIRS)
+
+
+def validate_almanac_root_field(value: Path | str | None) -> Path:
+    try:
+        return normalize_almanac_root(value)
+    except ValueError as error:
+        raise ValueError(str(error)) from error

codealmanac/services/workspaces/service.py

@@ -0,0 +1,303 @@
+from datetime import UTC, datetime
+from hashlib import sha256
+from pathlib import Path
+
+from codealmanac.core.errors import ConflictError, NotFoundError, ValidationFailed
+from codealmanac.core.paths import normalize_path
+from codealmanac.core.slug import to_kebab_case
+from codealmanac.services.workspaces.models import (
+    DropWorkspaceResult,
+    Workspace,
+    WorkspaceListItem,
+    WorkspaceListResult,
+    WorkspaceRegistryEntry,
+    WorkspaceRegistryStatus,
+)
+from codealmanac.services.workspaces.requests import (
+    DropWorkspaceRequest,
+    RegisterWorkspaceRequest,
+    SelectWorkspaceRequest,
+)
+from codealmanac.services.workspaces.roots import (
+    DEFAULT_ALMANAC_ROOT,
+    AlmanacRootMatch,
+    is_initialized_almanac_root,
+    nearest_almanac_root,
+)
+from codealmanac.services.workspaces.store import WorkspaceRegistryStore
+
+
+class WorkspacesService:
+    def __init__(self, store: WorkspaceRegistryStore):
+        self.store = store
+
+    def initialization_target(
+        self,
+        path: Path,
+        almanac_root: Path | None,
+    ) -> AlmanacRootMatch:
+        normalized = normalize_path(path)
+        if normalized.is_file():
+            normalized = normalized.parent
+        if almanac_root is None:
+            selected = containing_workspace(normalized, self.list())
+            if selected is not None:
+                return AlmanacRootMatch(
+                    repo_root=selected.root_path,
+                    almanac_root=selected.almanac_root,
+                    almanac_path=selected.almanac_path,
+                )
+            almanac_root = DEFAULT_ALMANAC_ROOT
+        existing = nearest_almanac_root(normalized, (almanac_root,))
+        if existing is not None:
+            return existing
+        return AlmanacRootMatch(
+            repo_root=normalized,
+            almanac_root=almanac_root,
+            almanac_path=normalized / almanac_root,
+        )
+
+    def register(self, request: RegisterWorkspaceRequest) -> Workspace:
+        root_path = normalize_path(request.root_path)
+        almanac_path = root_path / request.almanac_root
+        existing = entry_by_exact_path(root_path, self.store.list())
+        name = workspace_name_for(
+            root_path,
+            request.name or (existing.name if existing is not None else None),
+        )
+        description = (
+            request.description.strip()
+            or (existing.description if existing is not None else "")
+        )
+        workspace = Workspace(
+            workspace_id=workspace_id_for(root_path),
+            name=name,
+            description=description,
+            root_path=root_path,
+            almanac_root=request.almanac_root,
+            almanac_path=almanac_path,
+            registered_at=(
+                existing.registered_at if existing is not None else datetime.now(UTC)
+            ),
+        )
+        return self.store.remember(workspace).to_workspace()
+
+    def get(self, workspace_id: str) -> Workspace:
+        entry = self.store.find_by_workspace_id(workspace_id)
+        if entry is None:
+            raise NotFoundError("workspace", workspace_id)
+        return entry.to_workspace()
+
+    def select(self, request: SelectWorkspaceRequest) -> Workspace:
+        entries = self.store.list()
+        selected = entry_by_workspace_id(request.selector, entries)
+        if selected is not None:
+            return selected.to_workspace()
+        selected = entry_by_name(request.selector, entries)
+        if selected is not None:
+            return selected.to_workspace()
+        selected = entry_by_path(request, entries)
+        if selected is not None:
+            return selected.to_workspace()
+        raise NotFoundError("workspace", request.selector)
+
+    def resolve(self, path: Path) -> Workspace:
+        normalized = normalize_path(path)
+        selected = containing_workspace(normalized, self.list())
+        if selected is not None:
+            return selected
+        match = nearest_almanac_root(normalized, self.discoverable_almanac_roots())
+        if match is None:
+            raise NotFoundError("workspace", str(path))
+        return self.register(
+            RegisterWorkspaceRequest(
+                root_path=match.repo_root,
+                almanac_root=match.almanac_root,
+            )
+        )
+
+    def validate_path(self, workspace_id: str, path: Path) -> Path:
+        workspace = self.get(workspace_id)
+        normalized = normalize_path(path)
+        if not contains_path(workspace.root_path, normalized):
+            raise ValidationFailed(
+                f"path is outside workspace {workspace.name}: {normalized}"
+            )
+        return normalized
+
+    def list(self) -> list[Workspace]:
+        return [entry.to_workspace() for entry in self.store.list()]
+
+    def list_registry(self) -> WorkspaceListResult:
+        return WorkspaceListResult(
+            items=tuple(
+                WorkspaceListItem(
+                    workspace=entry.to_workspace(),
+                    status=workspace_registry_status(entry.to_workspace()),
+                )
+                for entry in self.store.list()
+            )
+        )
+
+    def drop(self, request: DropWorkspaceRequest) -> DropWorkspaceResult:
+        entries = self.store.list()
+        selected = select_registry_entry(
+            SelectWorkspaceRequest(
+                selector=request.selector,
+                base_path=request.base_path,
+            ),
+            entries,
+        )
+        if selected is None:
+            raise NotFoundError("workspace", request.selector)
+        remaining = [
+            entry
+            for entry in entries
+            if entry.workspace_id != selected.workspace_id
+        ]
+        self.store.replace(remaining)
+        return DropWorkspaceResult(dropped=(selected.to_workspace(),))
+
+    def drop_missing(self) -> DropWorkspaceResult:
+        entries = self.store.list()
+        dropped = tuple(
+            entry.to_workspace()
+            for entry in entries
+            if workspace_registry_status(entry.to_workspace())
+            != WorkspaceRegistryStatus.AVAILABLE
+        )
+        remaining = [
+            entry
+            for entry in entries
+            if workspace_registry_status(entry.to_workspace())
+            == WorkspaceRegistryStatus.AVAILABLE
+        ]
+        self.store.replace(remaining)
+        return DropWorkspaceResult(dropped=dropped)
+
+    def discoverable_almanac_roots(self) -> tuple[Path, ...]:
+        roots = [DEFAULT_ALMANAC_ROOT]
+        for workspace in self.list():
+            if workspace.almanac_root not in roots:
+                roots.append(workspace.almanac_root)
+        return tuple(roots)
+
+    @property
+    def registry_path(self) -> Path:
+        return self.store.path
+
+
+def workspace_name_for(root_path: Path, requested_name: str | None) -> str:
+    name = to_kebab_case(requested_name or root_path.name)
+    if not name:
+        raise ValidationFailed("could not derive a workspace name; pass --name")
+    return name
+
+
+def workspace_id_for(root_path: Path) -> str:
+    digest = sha256(str(root_path).encode("utf-8")).hexdigest()[:16]
+    return f"w_{digest}"
+
+
+def entry_by_workspace_id(
+    selector: str,
+    entries: list[WorkspaceRegistryEntry],
+) -> WorkspaceRegistryEntry | None:
+    for entry in entries:
+        if entry.workspace_id == selector:
+            return entry
+    return None
+
+
+def entry_by_name(
+    selector: str,
+    entries: list[WorkspaceRegistryEntry],
+) -> WorkspaceRegistryEntry | None:
+    matches = [
+        entry
+        for entry in entries
+        if entry.name.casefold() == selector.casefold()
+    ]
+    if len(matches) > 1:
+        raise ConflictError(f"workspace selector is ambiguous: {selector}")
+    if len(matches) == 1:
+        return matches[0]
+    return None
+
+
+def entry_by_path(
+    request: SelectWorkspaceRequest,
+    entries: list[WorkspaceRegistryEntry],
+) -> WorkspaceRegistryEntry | None:
+    selector_path = explicit_selector_path(request)
+    if selector_path is None:
+        return None
+    for entry in entries:
+        if same_path(entry.path, selector_path):
+            return entry
+    return None
+
+
+def select_registry_entry(
+    request: SelectWorkspaceRequest,
+    entries: list[WorkspaceRegistryEntry],
+) -> WorkspaceRegistryEntry | None:
+    selected = entry_by_workspace_id(request.selector, entries)
+    if selected is not None:
+        return selected
+    selected = entry_by_name(request.selector, entries)
+    if selected is not None:
+        return selected
+    return entry_by_path(request, entries)
+
+
+def entry_by_exact_path(
+    path: Path,
+    entries: list[WorkspaceRegistryEntry],
+) -> WorkspaceRegistryEntry | None:
+    for entry in entries:
+        if same_path(entry.path, path):
+            return entry
+    return None
+
+
+def explicit_selector_path(request: SelectWorkspaceRequest) -> Path | None:
+    if not is_path_selector(request.selector):
+        return None
+    path = Path(request.selector).expanduser()
+    if path.is_absolute():
+        return normalize_path(path)
+    if request.base_path is None:
+        return None
+    return normalize_path(request.base_path / path)
+
+
+def is_path_selector(selector: str) -> bool:
+    return selector.startswith(("/", "~", ".")) or "/" in selector
+
+
+def containing_workspace(path: Path, workspaces: list[Workspace]) -> Workspace | None:
+    matches = [
+        workspace
+        for workspace in workspaces
+        if contains_path(workspace.root_path, path)
+    ]
+    if len(matches) == 0:
+        return None
+    return max(matches, key=lambda workspace: len(workspace.root_path.parts))
+
+
+def contains_path(root_path: Path, path: Path) -> bool:
+    return path == root_path or root_path in path.parents
+
+
+def same_path(left: Path, right: Path) -> bool:
+    return normalize_path(left) == normalize_path(right)
+
+
+def workspace_registry_status(workspace: Workspace) -> WorkspaceRegistryStatus:
+    if not workspace.root_path.is_dir():
+        return WorkspaceRegistryStatus.MISSING_REPO
+    if not is_initialized_almanac_root(workspace.almanac_path):
+        return WorkspaceRegistryStatus.MISSING_ALMANAC
+    return WorkspaceRegistryStatus.AVAILABLE

codealmanac/services/workspaces/store.py

@@ -0,0 +1,127 @@
+import json
+from collections.abc import Sequence
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+from uuid import uuid4
+
+from pydantic import TypeAdapter, ValidationError
+
+from codealmanac.core.errors import ValidationFailed
+from codealmanac.core.paths import normalize_path
+from codealmanac.services.workspaces.models import (
+    Workspace,
+    WorkspaceRegistryEntry,
+)
+
+
+class WorkspaceRegistryStore:
+    def __init__(self, path: Path):
+        self.path = normalize_path(path)
+
+    def remember(self, workspace: Workspace) -> WorkspaceRegistryEntry:
+        entries = [
+            entry
+            for entry in self.list()
+            if not same_workspace(entry, workspace)
+        ]
+        entry = registry_entry_for(workspace)
+        entries.append(entry)
+        write_entries(self.path, entries)
+        return entry
+
+    def replace(self, entries: Sequence[WorkspaceRegistryEntry]) -> None:
+        write_entries(self.path, list(entries))
+
+    def find_by_workspace_id(self, workspace_id: str) -> WorkspaceRegistryEntry | None:
+        for entry in self.list():
+            if entry.workspace_id == workspace_id:
+                return entry
+        return None
+
+    def list(self) -> list[WorkspaceRegistryEntry]:
+        if not self.path.exists():
+            return []
+        text = self.path.read_text(encoding="utf-8").strip()
+        if text == "":
+            return []
+        return parse_entries(text)
+
+
+def registry_entry_for(workspace: Workspace) -> WorkspaceRegistryEntry:
+    return WorkspaceRegistryEntry(
+        name=workspace.name,
+        description=workspace.description,
+        path=workspace.root_path,
+        almanac_root=workspace.almanac_root,
+        registered_at=workspace.registered_at,
+        workspace_id=workspace.workspace_id,
+    )
+
+
+def same_workspace(entry: WorkspaceRegistryEntry, workspace: Workspace) -> bool:
+    return (
+        entry.workspace_id == workspace.workspace_id
+        or same_path(entry.path, workspace.root_path)
+        or entry.name.casefold() == workspace.name.casefold()
+    )
+
+
+def write_entries(path: Path, entries: list[WorkspaceRegistryEntry]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    data = entries_adapter().dump_python(entries, mode="json")
+    temporary = temporary_registry_path(path)
+    temporary.write_text(f"{json.dumps(data, indent=2)}\n", encoding="utf-8")
+    temporary.replace(path)
+
+
+def temporary_registry_path(path: Path) -> Path:
+    return path.with_name(f".{path.name}.{uuid4().hex}.tmp")
+
+
+def parse_entries(text: str) -> list[WorkspaceRegistryEntry]:
+    try:
+        raw_entries = json.loads(text)
+    except json.JSONDecodeError as error:
+        message = f"workspace registry is invalid JSON: {error}"
+        raise ValidationFailed(message) from error
+    if not isinstance(raw_entries, list):
+        raise ValidationFailed("workspace registry must be a JSON array")
+    return [parse_entry(raw_entry) for raw_entry in raw_entries]
+
+
+def parse_entry(raw_entry: Any) -> WorkspaceRegistryEntry:
+    if not isinstance(raw_entry, dict):
+        raise ValidationFailed("workspace registry entries must be objects")
+    upgraded = dict(raw_entry)
+    if "path" not in upgraded:
+        raise ValidationFailed('workspace registry entry is missing "path"')
+    path = normalize_path(Path(str(upgraded["path"])))
+    upgraded["path"] = path
+    if "workspace_id" not in upgraded:
+        upgraded["workspace_id"] = workspace_id_for_path(path)
+    if "description" not in upgraded:
+        upgraded["description"] = ""
+    if "almanac_root" not in upgraded:
+        upgraded["almanac_root"] = "almanac"
+    if "registered_at" not in upgraded or upgraded["registered_at"] == "":
+        upgraded["registered_at"] = datetime.now(UTC).isoformat()
+    try:
+        return WorkspaceRegistryEntry.model_validate(upgraded)
+    except ValidationError as error:
+        message = f"workspace registry entry is invalid: {error}"
+        raise ValidationFailed(message) from error
+
+
+def entries_adapter() -> TypeAdapter[Sequence[WorkspaceRegistryEntry]]:
+    return TypeAdapter(Sequence[WorkspaceRegistryEntry])
+
+
+def workspace_id_for_path(path: Path) -> str:
+    from codealmanac.services.workspaces.service import workspace_id_for
+
+    return workspace_id_for(path)
+
+
+def same_path(left: Path, right: Path) -> bool:
+    return normalize_path(left) == normalize_path(right)

codealmanac/workflows/__init__.py

@@ -0,0 +1 @@
+

codealmanac/workflows/build/__init__.py

@@ -0,0 +1 @@
+

codealmanac/workflows/build/models.py

@@ -0,0 +1,8 @@
+from codealmanac.core.models import CodeAlmanacModel
+from codealmanac.services.index.models import IndexRefreshResult
+from codealmanac.services.workspaces.models import Workspace
+
+
+class BuildResult(CodeAlmanacModel):
+    workspace: Workspace
+    index: IndexRefreshResult

codealmanac/workflows/build/service.py

@@ -0,0 +1,45 @@
+from codealmanac.services.index.service import IndexService
+from codealmanac.services.wiki.service import WikiService
+from codealmanac.services.workspaces.models import Workspace
+from codealmanac.services.workspaces.requests import (
+    InitializeWorkspaceRequest,
+    RegisterWorkspaceRequest,
+)
+from codealmanac.services.workspaces.service import WorkspacesService
+from codealmanac.workflows.build.models import BuildResult
+
+
+class BuildWorkflow:
+    def __init__(
+        self,
+        workspaces: WorkspacesService,
+        wiki: WikiService,
+        index: IndexService,
+    ):
+        self.workspaces = workspaces
+        self.wiki = wiki
+        self.index = index
+
+    def initialize(self, request: InitializeWorkspaceRequest) -> Workspace:
+        return self._initialize_workspace(request)
+
+    def build(self, request: InitializeWorkspaceRequest) -> BuildResult:
+        workspace = self._initialize_workspace(request)
+        index = self.index.ensure_fresh(workspace.workspace_id)
+        return BuildResult(workspace=workspace, index=index)
+
+    def _initialize_workspace(self, request: InitializeWorkspaceRequest) -> Workspace:
+        target = self.workspaces.initialization_target(
+            request.path,
+            request.almanac_root,
+        )
+        workspace = self.workspaces.register(
+            RegisterWorkspaceRequest(
+                root_path=target.repo_root,
+                almanac_root=target.almanac_root,
+                name=request.name,
+                description=request.description,
+            )
+        )
+        self.wiki.initialize(workspace.workspace_id)
+        return workspace

codealmanac/workflows/garden/__init__.py

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

codealmanac/workflows/garden/models.py

@@ -0,0 +1,30 @@
+from pathlib import Path
+
+from codealmanac.core.models import CodeAlmanacModel
+from codealmanac.services.harnesses.models import HarnessRunResult
+from codealmanac.services.index.models import (
+    HealthReport,
+    IndexRefreshResult,
+    IndexSummary,
+)
+from codealmanac.services.runs.models import RunRecord
+from codealmanac.workflows.lifecycle import LifecycleMutationReport
+
+
+class GardenPromptPayload(CodeAlmanacModel):
+    workspace_name: str
+    workspace_root: Path
+    almanac_root: Path
+    pages_root: Path
+    topics_file: Path
+    index: IndexSummary
+    health: HealthReport
+    guidance: str | None = None
+
+
+class GardenResult(CodeAlmanacModel):
+    run: RunRecord
+    harness: HarnessRunResult
+    safety: LifecycleMutationReport
+    index: IndexRefreshResult
+    health_before: HealthReport