groundskeeping 0.1.0__py3-none-any.whl

groundskeeping/__init__.py

@@ -0,0 +1,17 @@
+"""Reusable operator TUI shell contracts.
+
+The package top level intentionally avoids importing Textual. Headless contracts,
+configuration inspection, and telemetry sampling should be importable in worker and test
+processes that do not construct an application.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("groundskeeping")
+except PackageNotFoundError:  # pragma: no cover - source checkout without install
+    __version__ = "0.0.0"
+
+__all__ = ["__version__"]

groundskeeping/app.py

@@ -0,0 +1,233 @@
+"""Textual application shell composed from consumer-owned pages."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+from typing import ClassVar
+
+from rich.text import Text
+from textual.app import App, ComposeResult
+from textual.binding import Binding
+from textual.containers import Vertical
+from textual.widget import Widget
+from textual.widgets import DataTable, Footer, Header, Label, Tab, Tabs, Tree
+
+from groundskeeping.contracts.actions import (
+    ActionRegistry,
+    AllowAllOperationPolicy,
+    DefaultResultPresenter,
+    OperationPolicy,
+    ResultPresenter,
+)
+from groundskeeping.contracts.jobs import (
+    JobManager,
+    JobPolicy,
+    SingleForegroundJobPolicy,
+)
+from groundskeeping.contracts.pages import (
+    NotifySeverity,
+    OperatorPage,
+    PageContext,
+    PageRegistration,
+    PageRegistry,
+    PageRoute,
+    PageSurfacePort,
+)
+from groundskeeping.contracts.views import (
+    CatalogueItem,
+    DetailView,
+    EmptyView,
+    SurfaceView,
+)
+from groundskeeping.navigation import SurfaceLease
+from groundskeeping.theme import GROUNDSKEEPING_THEME
+from groundskeeping.widgets import Workbench
+
+
+@dataclass(frozen=True)
+class OperatorAppSpec:
+    """Immutable composition root for a Groundskeeping application."""
+
+    app_id: str
+    title: str
+    subtitle: str | None
+    pages: tuple[PageRegistration, ...]
+    actions: ActionRegistry = field(default_factory=lambda: ActionRegistry(()))
+    operation_policy: OperationPolicy = field(default_factory=AllowAllOperationPolicy)
+    job_policy: JobPolicy = field(default_factory=SingleForegroundJobPolicy)
+    result_presenter: ResultPresenter = field(default_factory=DefaultResultPresenter)
+    default_page: str | None = None
+    metadata: Mapping[str, object] | None = None
+
+    def validate(self) -> PageRegistry:
+        routes = tuple(registration.route for registration in self.pages)
+        registry = PageRegistry(routes)
+        if len({id(registration.factory) for registration in self.pages}) != len(self.pages):
+            raise ValueError("Page registrations must use distinct factories.")
+        ActionRegistry(tuple(self.actions), page_keys=registry.keys())
+        if self.default_page is not None:
+            registry.get(self.default_page)
+        return registry
+
+
+class _WorkbenchSurface(PageSurfacePort):
+    def __init__(self, workbench: Workbench) -> None:
+        self._workbench = workbench
+        self._lease_by_page: dict[str, SurfaceLease] = {}
+        self._generation = 0
+
+    def show_catalogue(self, page_key: str, items: Sequence[CatalogueItem]) -> None:
+        self._workbench.populate_catalogue(items)
+        self._lease(page_key, "catalogue")
+
+    def show_view(self, page_key: str, view: SurfaceView) -> None:
+        self._workbench.show_surface(view)
+        self._lease(page_key, view.title)
+
+    def show_detail(self, page_key: str, detail: DetailView) -> None:
+        self._workbench.show_detail(detail)
+        self._lease(page_key, "detail")
+
+    def _lease(self, page_key: str, source_key: str) -> SurfaceLease:
+        self._generation += 1
+        lease = SurfaceLease(page_key=page_key, source_key=source_key, generation=self._generation)
+        self._lease_by_page[page_key] = lease
+        return lease
+
+
+class _AppPageContext(PageContext):
+    def __init__(self, app: OperatorApp, surface: PageSurfacePort) -> None:
+        self._app = app
+        self._surface = surface
+
+    @property
+    def surface(self) -> PageSurfacePort:
+        return self._surface
+
+    def refresh_bindings(self) -> None:
+        self._app.refresh_bindings()
+
+    def request_navigation(self, page_key: str) -> None:
+        self._app.show_page(page_key)
+
+    def notify(self, message: str, *, severity: NotifySeverity = "information") -> None:
+        self._app.notify(message, severity=severity)
+
+
+class OperatorApp(App[None]):
+    """Reusable application frame: header, tabs, mounted pages, and workbench."""
+
+    CSS_PATH: ClassVar[str] = "themes/groundskeeping.tcss"
+    BINDINGS: ClassVar[list[Binding]] = [
+        Binding("q", "quit", "Quit"),
+    ]
+
+    def __init__(self, spec: OperatorAppSpec) -> None:
+        self.spec = spec
+        self.registry = spec.validate()
+        super().__init__()
+        self.title = spec.title
+        self.sub_title = spec.subtitle or ""
+        self.jobs = JobManager(spec.job_policy)
+        self._active_page = spec.default_page or self.registry[0].key
+        self._workbench = Workbench()
+        self._surface = _WorkbenchSurface(self._workbench)
+        # Textual's App already owns an internal `_context()` method used during
+        # startup. Keep the page-facing context under a distinct name so the shell does
+        # not accidentally shadow framework internals.
+        self._page_context = _AppPageContext(self, self._surface)
+        self._pages: dict[str, OperatorPage] = {
+            registration.route.key: registration.factory(self._page_context)
+            for registration in spec.pages
+        }
+        self._catalogue_by_key: dict[str, CatalogueItem] = {}
+
+    def compose(self) -> ComposeResult:
+        yield Header(show_clock=True)
+        with Vertical(id="body"):
+            yield Tabs(
+                *(Tab(route.label, id=route.key) for route in self.registry),
+                active=self._active_page,
+                id="page-tabs",
+            )
+            with Vertical(id="workspace"):
+                yield Label("", id="workspace-title")
+                for route in self.registry:
+                    page = self._pages[route.key]
+                    if not isinstance(page, Widget):
+                        raise TypeError(f"Page {route.key!r} must be a Textual Widget.")
+                    page.add_class("operator-page")
+                    yield page
+                yield self._workbench
+        yield Footer()
+
+    def on_mount(self) -> None:
+        self.register_theme(GROUNDSKEEPING_THEME)
+        self.theme = GROUNDSKEEPING_THEME.name
+        self.show_page(self._active_page)
+
+    def on_tabs_tab_activated(self, event: Tabs.TabActivated) -> None:
+        if event.tabs.id == "page-tabs" and event.tab.id:
+            self.show_page(event.tab.id)
+
+    def on_tree_node_selected(self, event: Tree.NodeSelected[CatalogueItem]) -> None:
+        if event.control.id != "catalogue":
+            return
+        data = event.node.data
+        if isinstance(data, CatalogueItem):
+            self._select_catalogue_item(data)
+
+    def on_data_table_row_highlighted(self, event: DataTable.RowHighlighted) -> None:
+        if event.data_table.id == "result-table":
+            self._active_widget().row_highlighted(str(event.row_key.value), self._page_context)
+
+    def on_data_table_row_selected(self, event: DataTable.RowSelected) -> None:
+        if event.data_table.id == "result-table":
+            self._active_widget().row_selected(str(event.row_key.value), self._page_context)
+
+    def show_page(self, page_key: str) -> None:
+        route = self.registry.get(page_key)
+        previous = self._pages.get(self._active_page)
+        next_page = self._pages[page_key]
+        if previous is not None and previous is not next_page:
+            previous.deactivate(self._page_context)
+            if isinstance(previous, Widget):
+                previous.remove_class("-active")
+        self._active_page = page_key
+        page = next_page
+        if isinstance(page, Widget):
+            page.add_class("-active")
+        tabs = self.query_one("#page-tabs", Tabs)
+        if tabs.active != page_key:
+            tabs.active = page_key
+        page.activate(self._page_context)
+        self._render_page(route)
+
+    def _render_page(self, route: PageRoute) -> None:
+        heading = Text(route.label, style="bold")
+        heading.append("  -  ", style="grey62")
+        heading.append(route.purpose, style="grey62")
+        self.query_one("#workspace-title", Label).update(heading)
+        page = self._active_widget()
+        items = tuple(page.build_catalogue(self._page_context))
+        self._catalogue_by_key = {item.key: item for item in self._walk_catalogue(items)}
+        self._workbench.populate_catalogue(items)
+        try:
+            view = page.landing_view(self._page_context)
+        except Exception as exc:  # noqa: BLE001
+            view = EmptyView(title=route.label, message=f"Unable to render page: {exc}")
+        self._workbench.show_surface(view)
+
+    def _active_widget(self) -> OperatorPage:
+        return self._pages[self._active_page]
+
+    def _select_catalogue_item(self, item: CatalogueItem) -> None:
+        self._active_widget().catalogue_selected(item, self._page_context)
+
+    def _walk_catalogue(self, items: tuple[CatalogueItem, ...]) -> tuple[CatalogueItem, ...]:
+        walked: list[CatalogueItem] = []
+        for item in items:
+            walked.append(item)
+            walked.extend(self._walk_catalogue(item.children))
+        return tuple(walked)

groundskeeping/configurator/__init__.py

@@ -0,0 +1,18 @@
+"""Read-only configuration inspection models and adapters."""
+
+from groundskeeping.configurator.adapter import (
+    NativeConfigResourceAdapter,
+    OAConfiguratorAdapter,
+)
+from groundskeeping.configurator.models import (
+    ConfigApplyIntent,
+    ConfigDiff,
+    ConfigDiffEntry,
+    ConfigDraft,
+    ConfigResourceAdapter,
+    ConfigSectionView,
+    ConfigTarget,
+    ConfiguratorSnapshot,
+    EffectRef,
+    RedactedValue,
+)

groundskeeping/configurator/adapter.py

@@ -0,0 +1,227 @@
+"""Read-only adapter over the public shape of `oa-configurator` stack models."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from dataclasses import is_dataclass
+from pathlib import Path
+
+from groundskeeping.configurator.models import (
+    ConfigDiff,
+    ConfigDiffEntry,
+    ConfigDraft,
+    ConfigSectionView,
+    ConfigTarget,
+    ConfiguratorSnapshot,
+    RedactedValue,
+)
+from groundskeeping.contracts.actions import FieldSpec, ValidationIssue
+from groundskeeping.contracts.views import SemanticStatus, TreeNode, TreeView
+
+_SECRET_FIELD_NAMES = frozenset({"password", "secret", "token", "api_key"})
+
+
+class OAConfiguratorAdapter:
+    """Build safe, read-only views from public `oa-configurator` model objects.
+
+    The adapter is deliberately structural: tests and demos can pass fakes, while real
+    consumers pass `StackConfig` and `PackageConfigBase` instances from `oa-configurator`.
+    Editable drafts and persistence are intentionally left for a later phase that can use
+    a public revision-aware mutation API.
+    """
+
+    def snapshot(
+        self,
+        stack_config: object,
+        *,
+        config_path: str | Path | None = None,
+        package_configs: Iterable[object] = (),
+        title: str = "Stack configuration",
+    ) -> ConfiguratorSnapshot:
+        profile = self._string_attr(stack_config, "active_profile", "profile")
+        sections = (
+            self._mapping_section("database", "Databases", getattr(stack_config, "databases", None)),
+            self._mapping_section("resource", "Resources", getattr(stack_config, "resources", None)),
+            self._mapping_section("profile", "Profiles", getattr(stack_config, "profiles", None)),
+            self._mapping_section("alias", "Aliases", getattr(stack_config, "aliases", None)),
+            self._package_section(tuple(package_configs)),
+        )
+        return ConfiguratorSnapshot(
+            title=title,
+            profile=profile,
+            path=str(config_path) if config_path is not None else self._string_attr(stack_config, "path"),
+            sections=tuple(section for section in sections if section is not None),
+        )
+
+    def as_tree_view(self, snapshot: ConfiguratorSnapshot) -> TreeView:
+        rows = tuple(self._section_to_node(section) for section in snapshot.sections)
+        details = []
+        if snapshot.path:
+            details.append(f"path: {snapshot.path}")
+        if snapshot.profile:
+            details.append(f"profile: {snapshot.profile}")
+        return TreeView(
+            title=snapshot.title,
+            message="; ".join(details) if details else "read-only inspection",
+            status=SemanticStatus.INFO,
+            rows=rows,
+        )
+
+    def diff(
+        self,
+        draft: ConfigDraft,
+        *,
+        sensitive_fields: frozenset[str] = frozenset(),
+    ) -> ConfigDiff:
+        """Build a redacted structural diff for confirmation surfaces."""
+        fields = sorted(set(draft.original_fields) | set(draft.candidate_fields))
+        entries: list[ConfigDiffEntry] = []
+        for field in fields:
+            before = draft.original_fields.get(field)
+            after = draft.candidate_fields.get(field)
+            if before == after:
+                continue
+            sensitive = field in sensitive_fields or isinstance(before, RedactedValue) or isinstance(after, RedactedValue)
+            entries.append(
+                ConfigDiffEntry(
+                    field=field,
+                    before=RedactedValue() if sensitive else before,
+                    after=RedactedValue() if sensitive else after,
+                    sensitive=sensitive,
+                )
+            )
+        return ConfigDiff(target=draft.target, entries=tuple(entries))
+
+    def _mapping_section(
+        self,
+        kind: str,
+        title: str,
+        values: object,
+    ) -> ConfigSectionView | None:
+        mapping = self._as_mapping(values)
+        if not mapping:
+            return None
+        children = tuple(
+            ConfigSectionView(
+                target=ConfigTarget(kind=kind, key=str(key), title=str(key)),
+                fields=self._safe_fields(value),
+            )
+            for key, value in sorted(mapping.items(), key=lambda item: str(item[0]))
+        )
+        return ConfigSectionView(
+            target=ConfigTarget(kind=f"{kind}-group", key=kind, title=title),
+            fields={"count": len(children)},
+            children=children,
+        )
+
+    def _package_section(self, package_configs: tuple[object, ...]) -> ConfigSectionView | None:
+        if not package_configs:
+            return None
+        children = []
+        for package_config in package_configs:
+            key = self._string_attr(package_config, "package_key", "package_name", "name")
+            title = key or type(package_config).__name__
+            children.append(
+                ConfigSectionView(
+                    target=ConfigTarget(kind="package", key=title, title=title),
+                    fields=self._safe_fields(package_config),
+                )
+            )
+        return ConfigSectionView(
+            target=ConfigTarget(kind="package-group", key="packages", title="Packages"),
+            fields={"count": len(children)},
+            children=tuple(children),
+        )
+
+    def _section_to_node(self, section: ConfigSectionView) -> TreeNode:
+        return TreeNode(
+            label=section.target.title,
+            status=section.target.status,
+            fields=section.fields,
+            children=tuple(self._section_to_node(child) for child in section.children),
+        )
+
+    def _safe_fields(self, value: object) -> Mapping[str, object]:
+        raw = self._object_mapping(value)
+        safe: dict[str, object] = {}
+        for key, item in raw.items():
+            name = str(key)
+            if name.lower() in _SECRET_FIELD_NAMES:
+                safe[name] = RedactedValue()
+            elif self._looks_scalar(item):
+                safe[name] = item
+            else:
+                safe[name] = self._summarize(item)
+        return safe
+
+    def _object_mapping(self, value: object) -> Mapping[str, object]:
+        mapping = self._as_mapping(value)
+        if mapping:
+            return {str(key): item for key, item in mapping.items()}
+        model_dump = getattr(value, "model_dump", None)
+        if callable(model_dump):
+            dumped = model_dump()
+            if isinstance(dumped, Mapping):
+                return {str(key): item for key, item in dumped.items()}
+        if is_dataclass(value):
+            return {
+                key: getattr(value, key)
+                for key in getattr(value, "__dataclass_fields__", {})
+            }
+        if hasattr(value, "__dict__"):
+            return {
+                key: item
+                for key, item in vars(value).items()
+                if not key.startswith("_")
+            }
+        return {"value": value}
+
+    def _as_mapping(self, value: object) -> Mapping[object, object]:
+        if isinstance(value, Mapping):
+            items: dict[object, object] = {key: item for key, item in value.items()}
+            return items
+        return {}
+
+    def _looks_scalar(self, value: object) -> bool:
+        return value is None or isinstance(value, str | int | float | bool | RedactedValue)
+
+    def _summarize(self, value: object) -> str:
+        mapping = self._as_mapping(value)
+        if mapping:
+            return f"{len(mapping)} entries"
+        if isinstance(value, (list, tuple, set, frozenset)):
+            return f"{len(value)} items"
+        return type(value).__name__
+
+    def _string_attr(self, value: object, *names: str) -> str | None:
+        for name in names:
+            item = getattr(value, name, None)
+            if item is not None:
+                return str(item)
+        return None
+
+
+class NativeConfigResourceAdapter:
+    """Fallback adapter for ordinary configuration sections.
+
+    Consumers can register exact adapters for richer resource semantics. This fallback is
+    intentionally plain: it offers display fields and validates nothing beyond the model
+    layer that `oa-configurator` will run during a real apply.
+    """
+
+    key = "native"
+
+    def supports(self, target: ConfigTarget) -> bool:
+        return True
+
+    def describe(self, target: ConfigTarget) -> ConfigSectionView:
+        return ConfigSectionView(target=target)
+
+    def fields(self, target: ConfigTarget) -> tuple[FieldSpec, ...]:
+        return ()
+
+    def validate(self, draft: ConfigDraft) -> tuple[ValidationIssue, ...]:
+        return ()
+
+    def post_apply_effects(self, draft: ConfigDraft) -> tuple[str, ...]:
+        return ()

groundskeeping/configurator/models.py

@@ -0,0 +1,110 @@
+"""Textual-free models for presenting stack configuration."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Protocol
+
+from groundskeeping.contracts.actions import FieldSpec, ValidationIssue
+from groundskeeping.contracts.views import SemanticStatus
+
+EffectRef = str
+
+
+@dataclass(frozen=True)
+class RedactedValue:
+    """Marker used when a known secret must not enter ordinary view models."""
+
+    label: str = "<redacted>"
+
+    def __str__(self) -> str:
+        return self.label
+
+
+@dataclass(frozen=True)
+class ConfigTarget:
+    """One selectable configuration target."""
+
+    kind: str
+    key: str
+    title: str
+    status: SemanticStatus = SemanticStatus.INFO
+
+
+@dataclass(frozen=True)
+class ConfigSectionView:
+    """Read-only view of one configuration section."""
+
+    target: ConfigTarget
+    fields: Mapping[str, object] = field(default_factory=dict)
+    children: tuple[ConfigSectionView, ...] = ()
+    notes: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class ConfiguratorSnapshot:
+    """Read-only snapshot of an effective `oa-configurator` stack."""
+
+    title: str
+    profile: str | None
+    path: str | None
+    sections: tuple[ConfigSectionView, ...]
+
+
+@dataclass(frozen=True)
+class ConfigDraft:
+    """Candidate edit against one configuration target.
+
+    The expected revision is opaque on purpose. `oa-configurator` owns how a real file or
+    in-memory stack is fingerprinted; the widget only carries the token back when asking
+    a public mutation service to apply the draft.
+    """
+
+    target: ConfigTarget
+    original_fields: Mapping[str, object]
+    candidate_fields: Mapping[str, object]
+    expected_revision: str | None = None
+
+
+@dataclass(frozen=True)
+class ConfigDiffEntry:
+    field: str
+    before: object
+    after: object
+    sensitive: bool = False
+
+
+@dataclass(frozen=True)
+class ConfigDiff:
+    target: ConfigTarget
+    entries: tuple[ConfigDiffEntry, ...]
+
+    @property
+    def changed(self) -> bool:
+        return bool(self.entries)
+
+
+@dataclass(frozen=True)
+class ConfigApplyIntent:
+    """UI-level request to apply a validated draft through `oa-configurator`."""
+
+    draft: ConfigDraft
+    diff: ConfigDiff
+    effects: tuple[EffectRef, ...] = ()
+
+
+class ConfigResourceAdapter(Protocol):
+    """Consumer extension point for richer resource-specific presentation."""
+
+    key: str
+
+    def supports(self, target: ConfigTarget) -> bool: ...
+
+    def describe(self, target: ConfigTarget) -> ConfigSectionView: ...
+
+    def fields(self, target: ConfigTarget) -> tuple[FieldSpec, ...]: ...
+
+    def validate(self, draft: ConfigDraft) -> tuple[ValidationIssue, ...]: ...
+
+    def post_apply_effects(self, draft: ConfigDraft) -> tuple[EffectRef, ...]: ...

groundskeeping/contracts/__init__.py

@@ -0,0 +1,57 @@
+"""Public headless contracts for composing a Groundskeeping application."""
+
+from groundskeeping.contracts.actions import (
+    ActionContext,
+    ActionOutcome,
+    ActionRegistry,
+    ActionSpec,
+    AllowAllOperationPolicy,
+    ChoiceOption,
+    Confirmation,
+    DefaultResultPresenter,
+    ExecutionKind,
+    FieldKind,
+    FieldSpec,
+    OperationPolicy,
+    ResultPresenter,
+    ValidationIssue,
+    run_action_sync,
+)
+from groundskeeping.contracts.jobs import (
+    BlockDecision,
+    CancellationMode,
+    CancellationRequested,
+    CancellationToken,
+    JobManager,
+    JobPolicy,
+    JobSnapshot,
+    JobSpec,
+    ProgressEvent,
+    ProgressSink,
+    RecordingProgressSink,
+    SingleForegroundJobPolicy,
+    ThreadCancellationToken,
+)
+from groundskeeping.contracts.pages import (
+    NotifySeverity,
+    OperatorPage,
+    PageContext,
+    PageRegistration,
+    PageRegistry,
+    PageRoute,
+    PageSurfacePort,
+)
+from groundskeeping.contracts.views import (
+    CatalogueItem,
+    DetailView,
+    EmptyView,
+    KeyValueView,
+    LoadingView,
+    SemanticStatus,
+    SurfaceView,
+    TableRow,
+    TableView,
+    TextView,
+    TreeNode,
+    TreeView,
+)