mateu-ui 3.0.0a418__py3-none-any.whl

mateu_core/__init__.py

@@ -0,0 +1,24 @@
+"""The Mateu engine: route registry, reflection mapper, and the sync use-case."""
+
+from ._version import __version__
+from .action_guard import MateuForbiddenException
+from .importwizard import ColumnMapping, ImportWizard, RowIssue, detect_separator, parse_csv
+from .mapper import ReflectionMapper
+from .registry import MateuRegistry, normalize, type_name
+from .sync_handler import RunActionRq, SyncHandler
+
+__all__ = [
+    "ColumnMapping",
+    "ImportWizard",
+    "MateuForbiddenException",
+    "MateuRegistry",
+    "ReflectionMapper",
+    "RowIssue",
+    "RunActionRq",
+    "SyncHandler",
+    "detect_separator",
+    "normalize",
+    "parse_csv",
+    "type_name",
+    "__version__",
+]

mateu_core/_version.py

@@ -0,0 +1,8 @@
+"""The single source of the package version.
+
+Development builds carry ``3.0.0.dev0``. The release workflow rewrites this line from the release
+tag (``v3.0-alpha.406`` → ``3.0.0a406``, see ``scripts/set_version.py``) before building, so the
+PyPI package moves in lockstep with the Maven artifacts.
+"""
+
+__version__ = "3.0.0a418"

mateu_core/action_guard.py

@@ -0,0 +1,276 @@
+"""The security gate of the action pipeline (mirrors Java's action authorization).
+
+An ``actionId`` arrives from the wire, so it must only ever reach a method DECLARED as an action.
+:func:`resolve_action` accepts the member whose camelCase name is the action id only when:
+
+- its name does not start with ``_`` (no private, name-mangled or dunder members);
+- it is a plain function defined in a class body (``inspect.isfunction``) — never a nested
+  class, a ``staticmethod``/``classmethod`` object, a callable class attribute or a builtin;
+- it is marked as an action — ``@action``, ``@button`` or ``@fab`` — or its id is ADVERTISED by
+  the view: an ``OnRowSelected`` value, a ``@subscribe_to`` action, the view's refresh action,
+  any ``*action_id`` of its component tree (fluent archetype tree, ``@auto_page``-inferred tree
+  or the YAML layout bound to it), of its ``RuleSupplier`` rules or of its
+  ``AppActionsSupplier`` header actions;
+- framework base classes (``mateu_uidl``/``mateu_core``/…, ``object``, ``typing``) only
+  contribute MARKED methods — the advertised path never reaches them.
+
+Bulk row actions (``action-on-row-*``) only reach ``@list_toolbar_button`` methods
+(:func:`resolve_row_action`). Once resolved, :func:`ensure_may_invoke` enforces the access
+decorators at invocation (``eyes_only``, ``disabled_unless``, ``audience``); a denied invocation
+raises :class:`MateuForbiddenException` (HTTP 403 at the FastAPI edge) and the method never runs.
+A class-level ``@eyes_only`` refuses the whole type (:func:`ensure_class_access`). The field marker
+``EyesOnly`` is enforced on render and — see :func:`may_write` — on binding.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import inspect
+import logging
+from typing import Any, Callable
+
+from mateu_uidl import (
+    AppActionsSupplier,
+    EyesOnly,
+    OnRowSelected,
+    ReadOnlyUnless,
+    RuleSupplier,
+)
+from mateu_uidl import components as fluent
+
+from .naming import camel_case
+from .reflection import view_fields
+
+log = logging.getLogger("mateu.security")
+
+#: Decorator markers that make a method invocable as a view action.
+ACTION_MARKERS = ("__mateu_action__", "__mateu_button__", "__mateu_fab__")
+ROW_ACTION_MARKER = "__mateu_list_toolbar_button__"
+
+_FRAMEWORK_PACKAGES = {"mateu_uidl", "mateu_core", "mateu_dtos", "mateu_fastapi"}
+_PLATFORM_MODULES = {"builtins", "typing", "abc", "collections.abc", "enum"}
+
+
+class MateuForbiddenException(Exception):
+    """A request the caller may not perform: an action gated by ``disabled_unless``/``audience``
+    the caller does not satisfy. The FastAPI adapter answers it with HTTP 403
+    and a generic body; the reason is only logged server-side."""
+
+
+def _is_framework_class(klass) -> bool:
+    module = getattr(klass, "__module__", "") or ""
+    return (
+        klass is object
+        or module in _PLATFORM_MODULES
+        or module.split(".")[0] in _FRAMEWORK_PACKAGES
+    )
+
+
+def _members(type_):
+    """``(name, value, declaring class)`` for every member the instance's attribute lookup would
+    resolve (the first definition along the MRO wins), skipping ``_``-prefixed names."""
+    seen: set[str] = set()
+    for klass in type_.__mro__:
+        for name, val in vars(klass).items():
+            if name in seen:
+                continue
+            seen.add(name)
+            if name.startswith("_"):
+                continue
+            yield name, val, klass
+
+
+def _has_marker(fn, markers) -> bool:
+    return any(hasattr(fn, m) for m in markers)
+
+
+def resolve_action(type_, action_id: str | None, advertised: Callable[[], set[str]]):
+    """The function ``action_id`` may invoke on a view of ``type_``, or ``None`` when no
+    declared action has that id (see the module docstring for the recognition rule)."""
+    if not action_id or action_id.startswith("_"):
+        return None
+    ids: set[str] | None = None
+    for name, val, klass in _members(type_):
+        if camel_case(name) != action_id or not inspect.isfunction(val):
+            continue
+        if _has_marker(val, ACTION_MARKERS):
+            return val
+        if _is_framework_class(klass):
+            continue
+        if ids is None:
+            ids = advertised()
+        if action_id in ids:
+            return val
+    return None
+
+
+GROUP_ACTION_MARKER = "__mateu_group_action__"
+
+
+def resolve_row_action(type_, name: str | None):
+    """The ``@list_toolbar_button`` (bulk) or ``@group_action`` (group header) function an
+    ``action-on-row-{name}`` may invoke, or None."""
+    if not name or name.startswith("_"):
+        return None
+    for member, val, _klass in _members(type_):
+        if (
+            camel_case(member) == name
+            and inspect.isfunction(val)
+            and (hasattr(val, ROW_ACTION_MARKER) or hasattr(val, GROUP_ACTION_MARKER))
+        ):
+            return val
+    return None
+
+
+def ensure_may_invoke(mapper, type_, fn, action_id: str | None) -> None:
+    """Enforces the access decorators of a resolved action at invocation: the render path only
+    disables/hides the button, the wire can still name the action."""
+    from .mapper import for_current_audience
+
+    reason = None
+    if not mapper.authorized(getattr(fn, "__mateu_eyes_only__", None)):
+        reason = "eyes_only"
+    elif not class_access_granted(mapper, type_):
+        reason = "class-level eyes_only/secured"
+    elif not mapper.authorized(getattr(fn, "__mateu_disabled_unless__", None)):
+        reason = "disabled_unless"
+    elif not for_current_audience(getattr(fn, "__mateu_audience__", None)):
+        reason = "audience"
+    if reason is not None:
+        deny(f"action '{action_id}' on {type_.__module__}.{type_.__qualname__} denied by {reason}")
+
+
+def class_gates(klass) -> list:
+    """The class-level access gates declared on ``klass`` itself: its ``@eyes_only`` and the
+    deprecated ``@secured`` (enforced since 3.0-alpha.412 as ``@eyes_only(permissions=[p])``)."""
+    return [
+        gate
+        for gate in (
+            klass.__dict__.get("__mateu_eyes_only__"),
+            klass.__dict__.get("__mateu_secured_gate__"),
+        )
+        if gate is not None
+    ]
+
+
+def class_access_granted(mapper, type_) -> bool:
+    """Whether the caller passes every class-level ``@eyes_only`` / ``@secured`` of ``type_`` and
+    of its bases (Java's ``WireTypePolicy.classLevelAccessGranted``)."""
+    if not isinstance(type_, type):
+        return True
+    for klass in type_.__mro__:
+        if any(not mapper.authorized(gate) for gate in class_gates(klass)):
+            return False
+    return True
+
+
+def ensure_class_access(mapper, type_, what: str = "request") -> None:
+    """Refuses (403) a request that names a type the caller may not see."""
+    if type_ is not None and not class_access_granted(mapper, type_):
+        deny(
+            f"{what} for {type_.__module__}.{type_.__qualname__}: "
+            "class-level eyes_only/secured not satisfied"
+        )
+
+
+def deny(what: str) -> None:
+    log.warning("Mateu request denied: %s — rejected with 403, the action did not run", what)
+    raise MateuForbiddenException(f"Forbidden: {what}")
+
+
+def may_write(mapper, f) -> bool:
+    """Whether the wire may WRITE field ``f``: an ``EyesOnly`` field the caller cannot see or a
+    ``ReadOnlyUnless`` field the caller cannot edit is dropped, keeping the server-side value
+    (mirrors Java's Hydrater)."""
+    return mapper.authorized(f.marker(EyesOnly)) and mapper.authorized(f.marker(ReadOnlyUnless))
+
+
+def advertised_ids(mapper, type_, instance, layout_override=None) -> set[str]:
+    """Every action id the view advertises besides its marked methods — the ids the mapper puts
+    on the wire (or the client sends back from the rendered tree) that route to a view method."""
+    ids: set[str] = set()
+    try:
+        fields = view_fields(type_)
+    except Exception as e:  # noqa: BLE001 - logged, not fatal
+        log.warning("advertised_ids failed, falling back (%s)", e)
+        fields = []
+    for f in fields:
+        on_row = f.marker(OnRowSelected)
+        if on_row is not None and on_row.value:
+            ids.add(camel_case(on_row.value))
+    for _event, act in getattr(type_, "__mateu_subscriptions__", ()) or ():
+        if act:
+            ids.add(camel_case(act))
+    # Section(add_action / edit_action / view_more_action) affordance buttons
+    from .mapper.layout import section_affordance_ids
+
+    ids.update(section_affordance_ids(type_))
+    # @app_shortcut(action_id=...) on an app class: the shortcut runs that app-level method
+    for _key, _route, shortcut_action, _label, _code in getattr(type_, "__mateu_app_shortcuts__", ()) or ():
+        if shortcut_action:
+            ids.add(shortcut_action)
+    refresh = getattr(type_, "__mateu_refresh_action__", None)
+    if isinstance(refresh, str) and refresh:
+        ids.add(refresh)
+
+    seen: set[int] = set()
+
+    def collect(source: Callable[[], Any]) -> None:
+        try:
+            root = source()
+        except Exception as e:  # noqa: BLE001 - logged, not fatal
+            log.warning("collect failed, falling back (%s)", e)
+            return
+        _walk(root, ids, seen, 0)
+
+    collect(lambda: layout_override if layout_override is not None else mapper.component_tree(instance))
+    collect(lambda: instance.rules() if isinstance(instance, RuleSupplier) else None)
+    collect(lambda: instance.app_actions() if isinstance(instance, AppActionsSupplier) else None)
+    # an app's menu: a rule leaf's RunAction names a method of the app (the shell dispatches it on
+    # the app-level rail, like a header action) — Java's MenuRuleActions
+    collect(lambda: mapper.map_app(type_) if "__mateu_app__" in getattr(type_, "__dict__", {}) else None)
+    return ids
+
+
+def _is_walkable(node) -> bool:
+    if isinstance(node, fluent.Component):
+        return True
+    module = getattr(type(node), "__module__", "") or ""
+    return module.split(".")[0] in _FRAMEWORK_PACKAGES
+
+
+def _walk(node, ids: set[str], seen: set[int], depth: int) -> None:
+    """Collects every string value held under a name ending in ``action_id`` (snake) or
+    ``ActionId`` (wire dict keys) anywhere in a fluent tree / mapped component graph."""
+    if node is None or depth > 64 or isinstance(node, (str, bytes, int, float, bool)):
+        return
+    if id(node) in seen:
+        return
+    seen.add(id(node))
+    if isinstance(node, dict):
+        for k, v in node.items():
+            if isinstance(v, str):
+                if isinstance(k, str) and v and (k.endswith("action_id") or k.endswith("ActionId")):
+                    ids.add(v)
+            else:
+                _walk(v, ids, seen, depth + 1)
+        return
+    if isinstance(node, (list, tuple, set, frozenset)):
+        for item in node:
+            _walk(item, ids, seen, depth + 1)
+        return
+    if not _is_walkable(node):
+        return
+    items: Any
+    if dataclasses.is_dataclass(node):
+        items = ((f.name, getattr(node, f.name, None)) for f in dataclasses.fields(node))
+    elif hasattr(type(node), "model_fields"):
+        items = ((name, getattr(node, name, None)) for name in type(node).model_fields)
+    else:
+        items = list(getattr(node, "__dict__", {}).items())
+    for name, value in items:
+        if isinstance(value, str):
+            if value and name.endswith("action_id"):
+                ids.add(value)
+        else:
+            _walk(value, ids, seen, depth + 1)

mateu_core/action_registry.py

@@ -0,0 +1,319 @@
+"""The app's ACTION catalogue — named, client-runnable actions (flows and REST calls) declared once
+and run by id from the shell menu or any page (the Python port of Java's ``ActionRegistry`` /
+``ActionCatalogMapper``).
+
+Two producers, one table: the DERIVED half is whatever ``ActionCatalogSupplier`` classes return; the
+AUTHORED half is ``specs/ui/actions.yaml`` plus any other YAML under the specs directory declaring
+``type: Actions`` (``MATEU_SPECS_DIR``), merged on top — authored wins, replacing outright. Ids are
+global. Only client-runnable entries are kept (steps or a rest action); anything else is server
+logic, which stays a view method — dropped with a warning naming it.
+
+Never fails: a broken file or supplier logs and yields fewer entries.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import threading
+from collections.abc import Iterable
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from mateu_dtos import Action, RestAction, UICommand
+from mateu_uidl.action_catalog import ActionCatalogSupplier, CatalogAction, CatalogRestAction
+from mateu_uidl.flow import CloseOverlay, Emit, FlowStep, MarkClean, MarkDirty, Navigate, RunAction
+
+from .rest_source_registry import entry_of, source_dto
+
+log = logging.getLogger("mateu.actions")
+
+FILE = "actions.yaml"
+TYPE = "Actions"
+
+
+class ActionRegistry:
+    def __init__(self, directory: str | None = None, suppliers: list[type] | None = None) -> None:
+        self._dir = Path(directory or os.environ.get("MATEU_SPECS_DIR") or Path("specs") / "ui")
+        self._suppliers = list(suppliers or [])
+        self._catalog: list[CatalogAction] | None = None
+        #: id → ``access:`` of an AUTHORED entry (Java's ``accessById``). Enforced like a page's
+        #: declared action: not shipped to a caller who does not satisfy it (it runs in the
+        #: browser, so not shipping it IS the enforcement), buttons naming it disabled, and a call
+        #: that reaches the server anyway refused with 403.
+        self._access_by_id: dict[str, Any] = {}
+        self._lock = threading.Lock()
+        from mateu_core import dev_specs
+
+        dev_specs.register(self)
+
+    def invalidate_specs(self) -> None:
+        """Dev mode: a spec changed — the catalogue is read again on next use."""
+        self._catalog = None
+        self._access_by_id.clear()
+
+    def catalog(self) -> list[CatalogAction]:
+        """The merged catalogue (authored over derived), loaded once."""
+        if self._catalog is None:
+            with self._lock:
+                if self._catalog is None:
+                    self._catalog = merged_over(self.authored(), self.derived())
+        return self._catalog
+
+    def get(self, action_id: str | None) -> CatalogAction | None:
+        if not action_id:
+            return None
+        return next((a for a in self.catalog() if a.id == action_id.strip()), None)
+
+    def derived(self) -> list[CatalogAction]:
+        out: list[CatalogAction] = []
+        for supplier in self._suppliers:
+            try:
+                contributed = supplier().action_catalog() or []
+            except Exception as e:  # noqa: BLE001 - a failing supplier contributes nothing
+                log.warning("Action catalogue: %s failed (%s)", supplier.__name__, e)
+                continue
+            out.extend(a for a in contributed if isinstance(a, CatalogAction) and a.id)
+        return merged_over(client_runnable_only(out, "a supplier"), [])
+
+    def authored(self) -> list[CatalogAction]:
+        if not self._dir.is_dir():
+            return []
+        conventional = self._dir / FILE
+        files = [conventional] if conventional.is_file() else []
+        for path in sorted(p for p in self._dir.rglob("*") if p.suffix in (".yaml", ".yml")):
+            if path.resolve() == conventional.resolve():
+                continue
+            root = _load(path)
+            if isinstance(root, dict) and root.get("type") == TYPE:
+                files.append(path)
+        by_id: dict[str, CatalogAction] = {}
+        access_by_id: dict[str, Any] = {}
+        for path in files:
+            for action in _read(path, access_by_id):
+                by_id[action.id] = action
+        self._access_by_id = {k: v for k, v in access_by_id.items() if k in by_id}
+        return list(by_id.values())
+
+    # ── access (``access:`` on an entry) ──────────────────────────────────────
+    def access_of(self, action_id: str | None):
+        """The restriction of catalogue action ``action_id``, or None."""
+        self.catalog()
+        return self._access_by_id.get(action_id) if action_id else None
+
+    def grants(self, action_id: str | None, authorized) -> bool:
+        """Whether the caller (``authorized``: the mapper's gate check) may run ``action_id``."""
+        access = self.access_of(action_id)
+        return access is None or bool(authorized(access))
+
+    def refused_for(self, authorized) -> set[str]:
+        """The ids of the restricted catalogue actions the caller may NOT run."""
+        self.catalog()
+        if authorized is None:
+            return set()
+        return {i for i, access in self._access_by_id.items() if not authorized(access)}
+
+    def restricted_ids(self) -> set[str]:
+        self.catalog()
+        return set(self._access_by_id)
+
+    def restricts_any(self) -> bool:
+        self.catalog()
+        return bool(self._access_by_id)
+
+    def catalog_for(self, authorized) -> list[CatalogAction]:
+        """The catalogue without the entries the caller may not run."""
+        all_ = self.catalog()
+        if not self._access_by_id or authorized is None:
+            return all_
+        refused = self.refused_for(authorized)
+        return [a for a in all_ if a.id not in refused]
+
+    def wire(self, authorized=None) -> list[Action]:
+        """The catalogue on the wire (AppMetadata.actionCatalogue), flows lowered to commands —
+        without the entries the caller (``authorized``) may not run."""
+        return [to_dto(a) for a in self.catalog_for(authorized)]
+
+    def referenced_by(
+        self, referenced: Iterable[str], owned: Iterable[str], authorized=None
+    ) -> list[CatalogAction]:
+        """The catalogue entries an owner needs to carry: each referenced id it does NOT own, closed
+        transitively over RunAction steps. OWNER FIRST: an owned id is never replaced. With
+        ``authorized``, the entries the caller may not run are left out (nor followed)."""
+        known = set(owned)
+        if authorized is not None and self.restricts_any():
+            known |= self.refused_for(authorized)  # treated as owned: never added, never followed
+        found: list[CatalogAction] = []
+        pending = list(referenced)
+        while pending:
+            action_id = pending.pop(0)
+            entry = self.get(action_id) if action_id not in known else None
+            if entry is None:
+                continue
+            known.add(action_id)
+            found.append(entry)
+            pending.extend(s.action_id for s in entry.steps if isinstance(s, RunAction))
+        return found
+
+
+def merged_over(authored: list[CatalogAction], derived: list[CatalogAction]) -> list[CatalogAction]:
+    """Authored over derived, keyed by id: an authored entry replaces the derived one in place."""
+    by_id: dict[str, CatalogAction] = {a.id: a for a in derived}
+    for a in authored:
+        by_id[a.id] = a
+    return list(by_id.values())
+
+
+def client_runnable_only(actions: Iterable[CatalogAction], origin: Any) -> list[CatalogAction]:
+    accepted = []
+    for action in actions:
+        if action.client_runnable():
+            accepted.append(action)
+        else:
+            log.warning(
+                "Action catalogue: '%s' in %s is not client-runnable (it has neither steps nor a"
+                " restAction) and is ignored — server logic stays a view method",
+                action.id,
+                origin,
+            )
+    return accepted
+
+
+def _load(path: Path) -> Any:
+    try:
+        return yaml.safe_load(path.read_text(encoding="utf-8"))
+    except Exception:  # noqa: BLE001
+        return None
+
+
+def collect_ids(node: Any, out: set[str] | None = None) -> set[str]:
+    """Every ``actionId`` / ``*ActionId`` string a raw YAML tree names (Java's
+    ``ActionRegistry.collectIds``)."""
+    out = set() if out is None else out
+    if isinstance(node, dict):
+        for name, value in node.items():
+            if isinstance(value, str) and (name == "actionId" or name.endswith("ActionId")):
+                if value.strip():
+                    out.add(value)
+            else:
+                collect_ids(value, out)
+    elif isinstance(node, list):
+        for child in node:
+            collect_ids(child, out)
+    return out
+
+
+def catalogue_ids_named_by(tree: Any) -> set[str]:
+    """The action ids ``tree`` names that its own ``actions:`` do not declare — OWNER FIRST: an id
+    the page declares is the page's, never the catalogue's (Java's ``catalogueIdsNamedBy``)."""
+    ids = collect_ids(tree)
+    own = tree.get("actions") if isinstance(tree, dict) else None
+    if isinstance(own, list):
+        for action in own:
+            if isinstance(action, dict):
+                ids.discard(str(action.get("id")))
+    return ids
+
+
+def _read(path: Path, access_by_id: dict[str, Any] | None = None) -> list[CatalogAction]:
+    from .yaml_access import access_of
+
+    root = _load(path)
+    nodes = root.get("actions") if isinstance(root, dict) else root
+    if not isinstance(nodes, list):
+        return []
+    parsed = []
+    for node in nodes:
+        if not isinstance(node, dict):
+            continue
+        action_id = str(node.get("id") or "").strip()
+        if not action_id:
+            log.warning("Ignoring an action with no id in %s", path)
+            continue
+        if access_by_id is not None:
+            access = access_of(node.get("access"))
+            if access is not None:
+                access_by_id[action_id] = access
+            else:
+                access_by_id.pop(action_id, None)  # a later file redeclaring it without access
+        parsed.append(
+            CatalogAction(
+                id=action_id,
+                description=str(node.get("description") or ""),
+                steps=tuple(s for s in (_step(n) for n in node.get("steps") or []) if s is not None),
+                rest_action=_rest_action(node.get("restAction")),
+            )
+        )
+    return client_runnable_only(parsed, path)
+
+
+def _step(node: Any) -> FlowStep | None:
+    if not isinstance(node, dict):
+        return None
+    kind = node.get("type")
+    if kind == "Navigate":
+        return Navigate(str(node.get("route") or ""))
+    if kind == "Emit":
+        return Emit(str(node.get("event") or ""), node.get("payload"))
+    if kind == "CloseOverlay":
+        return CloseOverlay(node.get("event"))
+    if kind == "RunAction":
+        return RunAction(str(node.get("actionId") or ""))
+    if kind == "MarkClean":
+        return MarkClean()
+    if kind == "MarkDirty":
+        return MarkDirty()
+    log.warning("Ignoring a flow step of unknown type '%s'", kind)
+    return None
+
+
+def _rest_action(node: Any) -> CatalogRestAction | None:
+    if not isinstance(node, dict):
+        return None
+    # reuse the source reader of the REST catalogue (an entry nests its request under `source:`)
+    entry = entry_of({"name": "_", "source": node.get("source")})
+    if entry is None:
+        return None
+    return CatalogRestAction(
+        source=entry.source,
+        success_message=node.get("successMessage"),
+        result_path=node.get("resultPath"),
+    )
+
+
+def lower(step: FlowStep) -> UICommand:
+    """A step as the one wire command it is, with no target (Java's ActionDtoMapper: the client
+    applies it on the component that fired the action)."""
+    return step.to_command().model_copy(update={"target_component_id": None})
+
+
+def to_dto(action: CatalogAction) -> Action:
+    """One catalogue entry on the wire (Java's ActionDtoMapper.mapAction)."""
+    rest = action.rest_action
+    return Action(
+        id=action.id,
+        validation_required=False,
+        rest_action=(
+            RestAction(
+                source=source_dto(rest.source),
+                success_message=rest.success_message,
+                result_path=rest.result_path,
+            )
+            if rest is not None
+            else None
+        ),
+        commands=[lower(s) for s in action.steps] or None,
+    )
+
+
+__all__ = [
+    "ActionRegistry",
+    "ActionCatalogSupplier",
+    "catalogue_ids_named_by",
+    "collect_ids",
+    "merged_over",
+    "to_dto",
+    "lower",
+]

mateu_core/capabilities.py

@@ -0,0 +1,49 @@
+"""The capability vocabulary — the Python mirror of Java's ``io.mateu.uidl.Capabilities``.
+
+An app advertises, on ``AppMetadata.requiredCapabilities``, the tokens it REQUIRES from whatever
+renderer/shell hosts it; a renderer advertises what it PROVIDES. Compatibility across the embedding
+boundary is negotiated BY CAPABILITY, not by a fixed version window. Most tokens are DERIVED from
+the app's own metadata; a developer can also DECLARE extra ones via ``@app(requires=[...])``.
+
+The token strings are the contract shared with the frontend (``libs/mateu`` capabilities.ts), the
+Java backend and the .NET port — keep them in step. Adding a capability is additive; never rename
+or repurpose an existing token.
+"""
+
+#: Server-sent events: long-running actions stream, and/or the AI chat endpoint.
+SSE = "sse"
+
+#: An app-scope data source fetched once on boot (AppMetadata.appDataSource).
+APP_DATA = "app-data"
+
+#: A named REST source catalogue the surfaces reference by ref.
+REST_SOURCES = "rest-sources"
+
+#: The command-center palette FAB (Ask-Oracle pattern).
+COMMAND_CENTER = "command-center"
+
+#: Global entity search wired into the ⌘K palette / command center.
+GLOBAL_SEARCH = "global-search"
+
+#: The notification inbox bell.
+NOTIFICATIONS = "notifications"
+
+#: App-header context selectors (@app_context).
+CONTEXT_SELECTORS = "context-selectors"
+
+#: App-header action buttons (AppActionsSupplier).
+HEADER_ACTIONS = "header-actions"
+
+#: Every token this build knows about — the set a full renderer PROVIDES.
+ALL = frozenset(
+    {
+        SSE,
+        APP_DATA,
+        REST_SOURCES,
+        COMMAND_CENTER,
+        GLOBAL_SEARCH,
+        NOTIFICATIONS,
+        CONTEXT_SELECTORS,
+        HEADER_ACTIONS,
+    }
+)