groundskeeping 0.1.0__py3-none-any.whl

groundskeeping/contracts/actions.py

@@ -0,0 +1,360 @@
+"""Generic action, field, and result contracts.
+
+Consumers own the verbs and the effects. Groundskeeping owns the repeatable operator
+sequence around those verbs: describe fields, parse input, ask policy whether to proceed,
+run with progress/cancellation context, and render a generic outcome.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterator, Mapping, Sequence
+from dataclasses import dataclass, field
+from decimal import Decimal, InvalidOperation
+from enum import StrEnum
+from pathlib import Path
+from typing import Protocol
+
+from groundskeeping.contracts.jobs import (
+    CancellationMode,
+    CancellationToken,
+    ProgressEvent,
+    ProgressSink,
+    RecordingProgressSink,
+)
+from groundskeeping.contracts.views import EmptyView, SemanticStatus, SurfaceView
+
+
+class FieldKind(StrEnum):
+    TEXT = "text"
+    INTEGER = "integer"
+    DECIMAL = "decimal"
+    BOOLEAN = "boolean"
+    CHOICE = "choice"
+    EXISTING_PATH = "existing_path"
+    OUTPUT_PATH = "output_path"
+    SECRET = "secret"
+    MULTILINE = "multiline"
+
+
+class ExecutionKind(StrEnum):
+    QUICK = "quick"
+    BACKGROUND = "background"
+    LONG_RUNNING = "long_running"
+
+
+@dataclass(frozen=True)
+class ChoiceOption:
+    value: str
+    label: str
+    description: str | None = None
+
+
+@dataclass(frozen=True)
+class ValidationIssue:
+    message: str
+    field_key: str | None = None
+    status: SemanticStatus = SemanticStatus.ERROR
+
+
+@dataclass(frozen=True)
+class ParsedField:
+    key: str
+    value: object
+    redacted: object
+
+
+Validator = Callable[[object], ValidationIssue | None]
+
+
+@dataclass(frozen=True)
+class FieldSpec:
+    """Declarative input field used by forms and headless tests."""
+
+    key: str
+    label: str
+    kind: FieldKind = FieldKind.TEXT
+    required: bool = True
+    default: object | None = None
+    help: str | None = None
+    choices: tuple[ChoiceOption, ...] = ()
+    minimum: Decimal | int | None = None
+    maximum: Decimal | int | None = None
+    sensitive: bool = False
+    validator: Validator | None = field(default=None, compare=False, repr=False)
+
+    @property
+    def masks_value(self) -> bool:
+        return self.sensitive or self.kind is FieldKind.SECRET
+
+    def parse(self, raw: object) -> ParsedField:
+        """Parse one field value and return both real and presentation-safe values."""
+        value = self.default if raw in (None, "") else raw
+        if value in (None, ""):
+            if self.required:
+                raise ValueError(f"{self.label} is required.")
+            return ParsedField(self.key, None, "<redacted>" if self.masks_value else None)
+
+        parsed = self._parse_value(value)
+        issue = self.validator(parsed) if self.validator is not None else None
+        if issue is not None:
+            raise ValueError(issue.message)
+        return ParsedField(
+            key=self.key,
+            value=parsed,
+            redacted="<redacted>" if self.masks_value and parsed is not None else parsed,
+        )
+
+    def _parse_value(self, value: object) -> object:
+        if self.kind in {FieldKind.TEXT, FieldKind.SECRET, FieldKind.MULTILINE}:
+            return str(value)
+        if self.kind is FieldKind.INTEGER:
+            if not isinstance(value, str | int | float | Decimal):
+                raise ValueError(f"{self.label} must be a whole number.")
+            try:
+                parsed = int(value)
+            except ValueError as exc:
+                raise ValueError(f"{self.label} must be a whole number.") from exc
+            self._check_bounds(parsed)
+            return parsed
+        if self.kind is FieldKind.DECIMAL:
+            try:
+                parsed = Decimal(str(value))
+            except InvalidOperation as exc:
+                raise ValueError(f"{self.label} must be a decimal number.") from exc
+            self._check_bounds(parsed)
+            return parsed
+        if self.kind is FieldKind.BOOLEAN:
+            if isinstance(value, bool):
+                return value
+            normalized = str(value).strip().lower()
+            if normalized in {"1", "true", "t", "yes", "y", "on"}:
+                return True
+            if normalized in {"0", "false", "f", "no", "n", "off"}:
+                return False
+            raise ValueError(f"{self.label} must be true or false.")
+        if self.kind is FieldKind.CHOICE:
+            parsed = str(value)
+            allowed = {choice.value for choice in self.choices}
+            if allowed and parsed not in allowed:
+                raise ValueError(f"{self.label} must be one of: {', '.join(sorted(allowed))}.")
+            return parsed
+        if self.kind is FieldKind.EXISTING_PATH:
+            path = Path(str(value)).expanduser()
+            if not path.exists():
+                raise ValueError(f"{self.label} does not exist: {path}")
+            return path
+        if self.kind is FieldKind.OUTPUT_PATH:
+            return Path(str(value)).expanduser()
+        raise ValueError(f"Unsupported field kind: {self.kind}")
+
+    def _check_bounds(self, value: Decimal | int) -> None:
+        if self.minimum is not None and value < self.minimum:
+            raise ValueError(f"{self.label} must be at least {self.minimum}.")
+        if self.maximum is not None and value > self.maximum:
+            raise ValueError(f"{self.label} must be at most {self.maximum}.")
+
+
+@dataclass(frozen=True)
+class Confirmation:
+    title: str
+    message: str
+    confirm_label: str = "Run"
+    dangerous: bool = False
+
+
+@dataclass(frozen=True)
+class ActionOutcome:
+    status: SemanticStatus
+    summary: str
+    view: SurfaceView
+    detail: object | None = None
+    refresh_pages: frozenset[str] = frozenset()
+
+
+@dataclass(frozen=True)
+class ActionContext:
+    """Everything a runner may touch while the action is in flight.
+
+    Deliberately narrow: a runner reports progress and checks for cancellation through this
+    object, so long-running domain work never needs to import a widget or reach the app.
+    """
+
+    progress: ProgressSink
+    cancellation: CancellationToken
+    action_id: str
+
+    def emit(
+        self,
+        event: str,
+        *,
+        phase: str | None = None,
+        completed: int = 0,
+        total: int | None = None,
+        unit: str | None = None,
+        message: str | None = None,
+    ) -> None:
+        self.progress.emit(
+            ProgressEvent(
+                event=event,
+                phase=phase,
+                completed=completed,
+                total=total,
+                unit=unit,
+                message=message,
+            )
+        )
+
+
+class ActionRunner(Protocol):
+    def __call__(self, params: Mapping[str, object], context: ActionContext) -> object: ...
+
+
+Preflight = Callable[[Mapping[str, object]], Sequence[ValidationIssue]]
+
+
+@dataclass(frozen=True)
+class ActionSpec:
+    """Declaration of one operator-facing command and the runner that performs it.
+
+    The spec carries everything the shell needs to present, gate, and execute the command
+    without knowing what it does: fields to parse, resources and effects for the operation
+    policy to reason about, and the cancellation mode the runner honours.
+    """
+
+    key: str
+    page_key: str
+    label: str
+    summary: str
+    runner: ActionRunner
+    command_hint: str | None = None
+    fields: tuple[FieldSpec, ...] = ()
+    execution: ExecutionKind = ExecutionKind.QUICK
+    cancellation: CancellationMode = CancellationMode.UNSUPPORTED
+    effect_refs: frozenset[str] = frozenset()
+    resource_refs: frozenset[str] = frozenset()
+    preflight: Preflight | None = field(default=None, compare=False, repr=False)
+
+    @property
+    def needs_params(self) -> bool:
+        return bool(self.fields)
+
+    @property
+    def long_running(self) -> bool:
+        return self.execution is ExecutionKind.LONG_RUNNING
+
+    def parse_params(self, raw: Mapping[str, object] | None = None) -> tuple[dict[str, object], dict[str, object]]:
+        raw = raw or {}
+        params: dict[str, object] = {}
+        redacted: dict[str, object] = {}
+        for spec in self.fields:
+            parsed = spec.parse(raw.get(spec.key))
+            params[spec.key] = parsed.value
+            redacted[spec.key] = parsed.redacted
+        return params, redacted
+
+
+class ResultPresenter(Protocol):
+    def present(self, action: ActionSpec, result: object) -> ActionOutcome: ...
+
+
+class DefaultResultPresenter:
+    """Present plain runner results without imposing a consumer report schema."""
+
+    def present(self, action: ActionSpec, result: object) -> ActionOutcome:
+        if isinstance(result, ActionOutcome):
+            return result
+        return ActionOutcome(
+            status=SemanticStatus.OK,
+            summary=f"{action.label} completed.",
+            view=EmptyView(title=action.label, message=str(result) if result is not None else "Completed."),
+        )
+
+
+class OperationPolicy(Protocol):
+    def describe_effects(self, action: ActionSpec, params: Mapping[str, object]) -> str: ...
+
+    def confirmation(self, action: ActionSpec, params: Mapping[str, object]) -> Confirmation | None: ...
+
+    def blocked_reason(
+        self,
+        action: ActionSpec,
+        params: Mapping[str, object],
+        active_jobs: Sequence[object],
+    ) -> str | None: ...
+
+
+class AllowAllOperationPolicy:
+    """Default policy for demos and tests; production consumers should be explicit."""
+
+    def describe_effects(self, action: ActionSpec, params: Mapping[str, object]) -> str:
+        if not action.effect_refs:
+            return "read-only"
+        return ", ".join(sorted(action.effect_refs))
+
+    def confirmation(self, action: ActionSpec, params: Mapping[str, object]) -> Confirmation | None:
+        if not action.effect_refs:
+            return None
+        return Confirmation(
+            title=action.label,
+            message=f"Effects: {self.describe_effects(action, params)}.",
+            dangerous=False,
+        )
+
+    def blocked_reason(
+        self,
+        action: ActionSpec,
+        params: Mapping[str, object],
+        active_jobs: Sequence[object],
+    ) -> str | None:
+        return None
+
+
+class ActionRegistry:
+    """Exact-key lookup for actions with startup validation."""
+
+    def __init__(self, actions: Sequence[ActionSpec], *, page_keys: Sequence[str] | None = None) -> None:
+        self._actions = tuple(actions)
+        self._by_key = {action.key: action for action in self._actions}
+        if len(self._actions) != len(self._by_key):
+            raise ValueError("Action keys must be unique.")
+        if page_keys is not None:
+            allowed = set(page_keys)
+            missing = sorted({action.page_key for action in self._actions} - allowed)
+            if missing:
+                raise ValueError(f"Actions reference unknown pages: {', '.join(missing)}")
+
+    def get(self, key: str) -> ActionSpec:
+        try:
+            return self._by_key[key]
+        except KeyError as exc:
+            raise KeyError(f"Unknown action: {key}") from exc
+
+    def for_page(self, page_key: str) -> tuple[ActionSpec, ...]:
+        return tuple(action for action in self._actions if action.page_key == page_key)
+
+    def __iter__(self) -> Iterator[ActionSpec]:
+        return iter(self._actions)
+
+
+def run_action_sync(
+    action: ActionSpec,
+    raw_params: Mapping[str, object] | None,
+    cancellation: CancellationToken,
+    *,
+    presenter: ResultPresenter | None = None,
+    action_id: str | None = None,
+) -> ActionOutcome:
+    """Run an action synchronously for tests, demos, and simple quick actions."""
+    params, _redacted = action.parse_params(raw_params)
+    if action.preflight is not None:
+        issues = tuple(action.preflight(params))
+        errors = [issue.message for issue in issues if issue.status is SemanticStatus.ERROR]
+        if errors:
+            raise ValueError("; ".join(errors))
+    context = ActionContext(
+        progress=RecordingProgressSink(),
+        cancellation=cancellation,
+        action_id=action_id or action.key,
+    )
+    result = action.runner(params, context)
+    return (presenter or DefaultResultPresenter()).present(action, result)

groundskeeping/contracts/jobs.py

@@ -0,0 +1,245 @@
+"""Portable progress, cancellation, and shell-job contracts.
+
+Shell jobs are deliberately smaller than consumer domain queues. A job here is work that
+this TUI process started and can present, gate, or cancel. Durable processing queues,
+leases, retries, and run records stay with the consuming application.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from enum import StrEnum
+from threading import Event
+from time import monotonic
+from typing import Protocol
+from uuid import uuid4
+
+
+class CancellationRequested(RuntimeError):
+    """Raised by cooperative runners when the operator has requested cancellation."""
+
+
+class CancellationMode(StrEnum):
+    """How the shell should present and route cancellation for an action."""
+
+    UNSUPPORTED = "unsupported"
+    COOPERATIVE = "cooperative"
+    IMMEDIATE = "immediate"
+
+
+class CancellationToken(Protocol):
+    """Structural cancellation contract passed into consumer runners."""
+
+    @property
+    def requested(self) -> bool: ...
+
+    def raise_if_requested(self) -> None: ...
+
+
+class ThreadCancellationToken:
+    """Thread-safe default cancellation token for ordinary shell workers."""
+
+    def __init__(self) -> None:
+        self._event = Event()
+
+    @property
+    def requested(self) -> bool:
+        return self._event.is_set()
+
+    def request(self) -> None:
+        self._event.set()
+
+    def raise_if_requested(self) -> None:
+        if self.requested:
+            raise CancellationRequested("Operation cancelled by the operator.")
+
+
+@dataclass(frozen=True)
+class ProgressEvent:
+    """One portable progress update emitted by a runner."""
+
+    event: str
+    phase: str | None = None
+    completed: int = 0
+    total: int | None = None
+    unit: str | None = None
+    message: str | None = None
+    timestamp: datetime = field(default_factory=lambda: datetime.now(UTC))
+
+    @property
+    def fraction(self) -> float | None:
+        if self.total in (None, 0):
+            return None
+        return max(0.0, min(1.0, self.completed / self.total))
+
+
+class ProgressSink(Protocol):
+    """Consumer runners call this; widgets never need to know the runner type."""
+
+    def emit(self, event: ProgressEvent) -> None: ...
+
+
+class RecordingProgressSink:
+    """Small sink used by tests, demos, and synchronous action execution."""
+
+    def __init__(self) -> None:
+        self.events: list[ProgressEvent] = []
+
+    def emit(self, event: ProgressEvent) -> None:
+        self.events.append(event)
+
+
+@dataclass(frozen=True)
+class JobSpec:
+    """What the shell needs to decide whether work may start."""
+
+    key: str
+    label: str
+    resources: frozenset[str] = frozenset()
+    effects: frozenset[str] = frozenset()
+    cancellation: CancellationMode = CancellationMode.UNSUPPORTED
+    foreground: bool = True
+
+
+@dataclass(frozen=True)
+class JobSnapshot:
+    """Immutable view of a shell job for policy, bars, and tests."""
+
+    job_id: str
+    spec: JobSpec
+    started_at: float
+    progress: ProgressEvent | None = None
+    cancelling: bool = False
+    metadata: Mapping[str, object] = field(default_factory=dict)
+
+    @property
+    def fraction(self) -> float | None:
+        return None if self.progress is None else self.progress.fraction
+
+    @property
+    def cancellable(self) -> bool:
+        return self.spec.cancellation is not CancellationMode.UNSUPPORTED
+
+    @property
+    def elapsed(self) -> float:
+        return max(0.0, monotonic() - self.started_at)
+
+    def describe(self) -> str:
+        if self.progress and self.progress.message:
+            return f"{self.spec.label}: {self.progress.message}"
+        if self.progress and self.progress.phase:
+            return f"{self.spec.label}: {self.progress.phase}"
+        return self.spec.label
+
+
+@dataclass(frozen=True)
+class BlockDecision:
+    """Policy answer for whether a candidate job can start."""
+
+    allowed: bool
+    reason: str | None = None
+
+    @classmethod
+    def allow(cls) -> BlockDecision:
+        return cls(True)
+
+    @classmethod
+    def block(cls, reason: str) -> BlockDecision:
+        return cls(False, reason)
+
+
+class JobPolicy(Protocol):
+    """In-process gate for shell jobs."""
+
+    def can_start(self, candidate: JobSpec, active: Sequence[JobSnapshot]) -> BlockDecision: ...
+
+
+class SingleForegroundJobPolicy:
+    """Default policy: one foreground job, plus no overlapping explicit resources."""
+
+    def can_start(self, candidate: JobSpec, active: Sequence[JobSnapshot]) -> BlockDecision:
+        if candidate.foreground and any(job.spec.foreground for job in active):
+            return BlockDecision.block("another foreground job is already running")
+        for job in active:
+            overlap = candidate.resources & job.spec.resources
+            if overlap:
+                resources = ", ".join(sorted(overlap))
+                return BlockDecision.block(f"resource already in use: {resources}")
+        return BlockDecision.allow()
+
+
+class JobManager:
+    """Multi-job-capable manager with a conservative default policy.
+
+    The manager does not execute work itself. Textual workers, threads, or synchronous test
+    harnesses own execution and report lifecycle changes back here.
+    """
+
+    def __init__(self, policy: JobPolicy | None = None) -> None:
+        self.policy = policy or SingleForegroundJobPolicy()
+        self._active: dict[str, tuple[JobSnapshot, ThreadCancellationToken]] = {}
+
+    @property
+    def active(self) -> tuple[JobSnapshot, ...]:
+        return tuple(snapshot for snapshot, _token in self._active.values())
+
+    @property
+    def foreground(self) -> JobSnapshot | None:
+        return next((job for job in self.active if job.spec.foreground), None)
+
+    def can_start(self, spec: JobSpec) -> BlockDecision:
+        return self.policy.can_start(spec, self.active)
+
+    def start(
+        self,
+        spec: JobSpec,
+        *,
+        job_id: str | None = None,
+        metadata: Mapping[str, object] | None = None,
+    ) -> tuple[JobSnapshot, ThreadCancellationToken]:
+        decision = self.can_start(spec)
+        if not decision.allowed:
+            raise RuntimeError(decision.reason or "Job cannot start.")
+        resolved_id = job_id or f"{spec.key}:{uuid4().hex}"
+        token = ThreadCancellationToken()
+        snapshot = JobSnapshot(
+            job_id=resolved_id,
+            spec=spec,
+            started_at=monotonic(),
+            metadata=dict(metadata or {}),
+        )
+        self._active[resolved_id] = (snapshot, token)
+        return snapshot, token
+
+    def update(self, job_id: str, progress: ProgressEvent) -> JobSnapshot:
+        snapshot, token = self._active[job_id]
+        updated = JobSnapshot(
+            job_id=snapshot.job_id,
+            spec=snapshot.spec,
+            started_at=snapshot.started_at,
+            progress=progress,
+            cancelling=snapshot.cancelling,
+            metadata=snapshot.metadata,
+        )
+        self._active[job_id] = (updated, token)
+        return updated
+
+    def request_cancel(self, job_id: str) -> JobSnapshot:
+        snapshot, token = self._active[job_id]
+        token.request()
+        updated = JobSnapshot(
+            job_id=snapshot.job_id,
+            spec=snapshot.spec,
+            started_at=snapshot.started_at,
+            progress=snapshot.progress,
+            cancelling=True,
+            metadata=snapshot.metadata,
+        )
+        self._active[job_id] = (updated, token)
+        return updated
+
+    def complete(self, job_id: str) -> JobSnapshot:
+        snapshot, _token = self._active.pop(job_id)
+        return snapshot