patchbai 0.1.0__py3-none-any.whl

patchbai/layout/engine.py

@@ -0,0 +1,241 @@
+import weakref
+from dataclasses import dataclass
+
+from patchbai.events import LayoutApplied, LayoutFailed
+from patchbai.layout.spec import Container, LayoutSpec, Panel, Tabs
+from patchbai.layout.titles import resolve_title
+
+
+# --- Operations -------------------------------------------------------------
+
+@dataclass(frozen=True)
+class MountPanel:
+    panel: Panel
+
+
+@dataclass(frozen=True)
+class UnmountPanel:
+    panel_id: str
+
+
+@dataclass(frozen=True)
+class UpdateProps:
+    panel_id: str
+    props: dict
+
+
+Operation = MountPanel | UnmountPanel | UpdateProps
+
+
+# --- Diff -------------------------------------------------------------------
+
+def _collect_panels(node, out: dict[str, Panel]) -> None:
+    if isinstance(node, Panel):
+        out[node.id] = node
+    elif isinstance(node, Tabs):
+        for c in node.children:
+            out[c.id] = c
+    elif isinstance(node, Container):
+        for c in node.children:
+            _collect_panels(c, out)
+
+
+def diff(old: LayoutSpec | None, new: LayoutSpec) -> list[Operation]:
+    """Compute the minimal set of mount/unmount/update operations to take the
+    rendered widget tree from `old` to `new`.
+
+    Note: this plan reuses widgets only when the panel id AND widget type are
+    unchanged. Container restructuring is handled by Task 14's apply step,
+    which rebuilds the container scaffolding from `new.layout` each call.
+    Reusing identical panels means no scroll-jump or focus-loss for the cases
+    that matter most (props-only changes)."""
+
+    old_panels: dict[str, Panel] = {}
+    new_panels: dict[str, Panel] = {}
+    if old is not None:
+        _collect_panels(old.layout, old_panels)
+    _collect_panels(new.layout, new_panels)
+
+    ops: list[Operation] = []
+
+    for pid, op in old_panels.items():
+        if pid not in new_panels or new_panels[pid].widget != op.widget:
+            ops.append(UnmountPanel(panel_id=pid))
+
+    for pid, np in new_panels.items():
+        if pid not in old_panels or old_panels[pid].widget != np.widget:
+            ops.append(MountPanel(panel=np))
+            continue
+        if old_panels[pid].props != np.props:
+            ops.append(UpdateProps(panel_id=pid, props=np.props))
+
+    return ops
+
+
+# --- Apply ------------------------------------------------------------------
+
+from textual.containers import Container as TxContainer
+from textual.containers import Horizontal, Vertical
+from textual.widget import Widget
+from textual.widgets import TabbedContent, TabPane
+
+from patchbai.layout.splitter import Splitter
+
+
+def _has_border_in_default_css(cls) -> bool:
+    """Heuristic: does this class (or an ancestor) declare a border in
+    DEFAULT_CSS? Used by the safety net so we don't clobber a widget's own
+    border style. Walks the MRO so subclasses inherit the answer.
+
+    Naive substring match — will false-positive on `border:` appearing in
+    a CSS comment or in a selector name like `.border-panel`. The failure
+    mode (skipping the safety net when we shouldn't) is cosmetic, not
+    functional, and rare enough to accept here."""
+    for base in cls.__mro__:
+        css = getattr(base, "DEFAULT_CSS", "") or ""
+        if isinstance(css, str) and ("border:" in css or "border-" in css):
+            return True
+    return False
+
+
+def _build(node, registry, path: tuple[int, ...] = ()) -> Widget:
+    if isinstance(node, Panel):
+        cls = registry.get(node.widget)
+        widget = cls(**node.props) if node.props else cls()
+        widget.id = f"panel-{node.id}"
+        widget.can_focus = True  # panels must be focusable so focus survives rebuilds
+        if node.size:
+            widget.styles.width = node.size if "%" in node.size or node.size.endswith("fr") else None
+            widget.styles.height = None
+        # Border safety net: widgets with no DEFAULT_CSS border get a default
+        # one so border_title renders. Widgets with their own border keep it.
+        # CSS variables (e.g. $surface-lighten-2) are not valid as inline style
+        # color values before mount — use a concrete grey that approximates the
+        # default dark-mode surface colour.
+        if not _has_border_in_default_css(cls):
+            widget.styles.border = ("round", "#3a3a3a")
+        # Title resolution (never aborts the apply on a buggy widget).
+        try:
+            widget.border_title = resolve_title(node, cls)
+        except Exception:
+            widget.border_title = cls.__name__
+        widget._patchbai_spec_path = path  # type: ignore[attr-defined]
+        return widget
+    if isinstance(node, Tabs):
+        panes = []
+        for i, child in enumerate(node.children):
+            inner = _build(child, registry, path + (i,))   # reuses Panel branch
+            label = child.title or _default_pane_label(child, registry)
+            panes.append(TabPane(label, inner, id=f"tabpane-{child.id}"))
+        initial_id = f"tabpane-{node.active or node.children[0].id}"
+        # TabbedContent.__init__ takes *titles as strings; passing TabPane
+        # objects there triggers render_str and fails pre-mount. Instead,
+        # construct with no positional args and load panes via _tab_content
+        # (the same slot that compose_add_child fills when using the context
+        # manager syntax), then set _initial for the active tab.
+        tc = TabbedContent(initial=initial_id)
+        tc._tab_content = list(panes)
+        if node.size:
+            tc.styles.width = node.size
+        tc._patchbai_spec_path = path  # type: ignore[attr-defined]
+        return tc
+    # Container
+    box_cls = Horizontal if node.type == "horizontal" else Vertical
+    built = [_build(c, registry, path + (i,)) for i, c in enumerate(node.children)]
+    # Interleave a draggable Splitter between each pair of siblings so the user
+    # can resize panels with the mouse. Single-child containers get no splitter.
+    interleaved: list[Widget] = []
+    for i, child in enumerate(built):
+        if i > 0:
+            # Splitter sits between spec children (i-1) and i of this Container.
+            interleaved.append(Splitter(
+                node.type, parent_path=path, prev_index=i - 1, next_index=i,
+            ))
+        interleaved.append(child)
+    box = box_cls(*interleaved)
+    if node.size:
+        box.styles.width = node.size
+    box._patchbai_spec_path = path  # type: ignore[attr-defined]
+    return box
+
+
+def _default_pane_label(panel: Panel, registry) -> str:
+    """Best-effort label for a TabPane when the panel has no explicit title.
+    Reuses resolve_title against the widget class so widgets that publish a
+    DEFAULT_BORDER_TITLE feed the tab label too."""
+    try:
+        cls = registry.get(panel.widget)
+        return resolve_title(panel, cls)
+    except Exception:
+        return panel.widget
+
+
+# Track the most recent applied spec per container, keyed by the container
+# instance itself. WeakKeyDictionary ensures stale entries gc out when the
+# container is no longer referenced — important since `apply` is called many
+# times per session in tests, and id-keyed caches are footguns once the
+# garbage collector reuses ids.
+_last_applied_spec: "weakref.WeakKeyDictionary[TxContainer, LayoutSpec]" = weakref.WeakKeyDictionary()
+
+
+async def apply(container: TxContainer, spec: LayoutSpec, registry,
+                *, layout_name: str | None = None,
+                apply_focus: bool = True) -> None:
+    """Replace `container`'s children with widgets built from `spec.layout`.
+
+    Behavior:
+    - **Idempotent fast-path:** if `spec` equals the last-applied spec for this
+      container, skip the rebuild entirely. A `LayoutApplied` event is still
+      fired so subscribers can refresh anything spec-derived (e.g., the
+      StatusBar's layout name).
+    - **Atomic build:** the new widget tree is fully constructed before any
+      existing child is removed. If `_build` raises (e.g., UnknownWidgetError),
+      a `LayoutFailed(error=str(exc))` event is published and the previous
+      mounted layout stays untouched. The exception is re-raised.
+    - **Focus preservation:** if `spec.focus` is None and a panel is currently
+      focused, restore that panel's id after the rebuild (provided the panel
+      survives in the new spec).
+    - **`apply_focus=False`** skips the focus call entirely. Use when applying
+      a layout into a TabPane that isn't the workspace's active tab — focusing
+      a widget inside a hidden pane causes Textual to switch the displayed
+      pane to the one containing that widget, which silently overrides the
+      caller's intended active tab.
+    """
+    bus = getattr(container.app, "event_bus", None)
+
+    # Fast-path: same spec → no rebuild.
+    if _last_applied_spec.get(container) == spec:
+        if bus is not None:
+            bus.publish(LayoutApplied(spec=spec, layout_name=layout_name))
+        return
+
+    # Atomic build (raises before any mount changes).
+    try:
+        new_children = [_build(spec.layout, registry)]
+    except Exception as e:
+        if bus is not None:
+            bus.publish(LayoutFailed(error=str(e)))
+        raise
+
+    # Snapshot focus.
+    snapshot_focus_id: str | None = None
+    try:
+        focused = container.app.focused
+        if focused is not None and focused.id and focused.id.startswith("panel-"):
+            snapshot_focus_id = focused.id[len("panel-"):]
+    except Exception:
+        pass
+
+    await container.remove_children()
+    await container.mount_all(new_children)
+
+    target = spec.focus or snapshot_focus_id
+    if target and apply_focus:
+        try:
+            container.query_one(f"#panel-{target}").focus()
+        except Exception:
+            pass
+
+    _last_applied_spec[container] = spec
+    if bus is not None:
+        bus.publish(LayoutApplied(spec=spec, layout_name=layout_name))

patchbai/layout/local_widgets.py

@@ -0,0 +1,188 @@
+from __future__ import annotations
+
+import importlib.util
+import logging
+import sys
+import tempfile
+import traceback
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+from textual.widget import Widget
+
+from patchbai.layout.registry import WidgetRegistry
+
+log = logging.getLogger(__name__)
+
+
+LoadStatus = Literal[
+    "ok",
+    "import_error",
+    "no_widget_class",
+    "ambiguous_class",
+    "name_collision",
+]
+
+
+@dataclass(frozen=True)
+class LoadOutcome:
+    path: Path
+    name: str
+    status: LoadStatus
+    error: str | None = None
+
+
+class LocalWidgetLoader:
+    """Walks a directory, imports every top-level .py file as an isolated
+    module, finds its Textual Widget subclass, and registers it.
+
+    Files starting with '_' or '.' are skipped.
+    Missing/empty directory yields an empty outcome list (not an error).
+    """
+
+    def __init__(self, dir_path: Path, registry: WidgetRegistry) -> None:
+        self._dir = Path(dir_path)
+        self._registry = registry
+
+    def load(self) -> list[LoadOutcome]:
+        if not self._dir.exists():
+            return []
+        outcomes: list[LoadOutcome] = []
+        for path in sorted(self._dir.iterdir()):
+            if not path.is_file() or path.suffix != ".py":
+                continue
+            if path.name.startswith(("_", ".")):
+                continue
+            outcomes.append(self._load_one(path))
+        return outcomes
+
+    def _load_one(self, path: Path) -> LoadOutcome:
+        stem = path.stem
+        # Use a unique module name to avoid collisions in sys.modules.
+        mod_name = f"_patchbai_local_widget_{stem}"
+        try:
+            spec = importlib.util.spec_from_file_location(mod_name, path)
+            assert spec is not None and spec.loader is not None
+            module = importlib.util.module_from_spec(spec)
+            sys.modules[mod_name] = module
+            spec.loader.exec_module(module)
+        except Exception:
+            tb = traceback.format_exc(limit=2)
+            return LoadOutcome(
+                path=path, name=stem, status="import_error", error=tb,
+            )
+
+        meta = getattr(module, "__patchbai_widget__", {}) or {}
+        if not isinstance(meta, dict):
+            meta = {}
+        name = meta.get("name") or _pascal(stem)
+
+        # Name-collision with an already-registered builtin: skip.
+        existing = self._registry._infos.get(name)
+        if existing is not None and existing.source == "builtin":
+            return LoadOutcome(
+                path=path, name=name, status="name_collision",
+                error=f"name {name!r} is reserved by the built-in registry",
+            )
+
+        cls, err = _find_widget_class_in_module(module, meta, name)
+        if cls is None:
+            return LoadOutcome(path=path, name=name, status=err or "no_widget_class")
+
+        self._registry.register(
+            name, cls,
+            description=meta.get("description", ""),
+            props_schema=dict(meta.get("props_schema") or {}),
+            source="local",
+        )
+        return LoadOutcome(path=path, name=name, status="ok")
+
+
+def _pascal(stem: str) -> str:
+    return "".join(part.capitalize() for part in stem.replace("-", "_").split("_") if part)
+
+
+def _find_widget_class_in_module(module, meta: dict, name: str):
+    """Returns (cls_or_none, status_on_failure)."""
+    # 1. Explicit entry_point in metadata.
+    ep = meta.get("entry_point")
+    if isinstance(ep, type) and issubclass(ep, Widget):
+        return ep, None
+
+    # 2. WIDGET_CLASS sentinel.
+    sentinel = getattr(module, "WIDGET_CLASS", None)
+    if isinstance(sentinel, type) and issubclass(sentinel, Widget):
+        return sentinel, None
+
+    # 3. Class named exactly `name`, defined in this module
+    #    (so an imported Widget subclass referenced by metadata `name`
+    #    doesn't accidentally register as a local widget).
+    by_name = getattr(module, name, None)
+    if (
+        isinstance(by_name, type)
+        and issubclass(by_name, Widget)
+        and getattr(by_name, "__module__", None) == module.__name__
+    ):
+        return by_name, None
+
+    # 4. Single Widget subclass DEFINED in this module.
+    candidates = []
+    for v in vars(module).values():
+        if (
+            isinstance(v, type)
+            and issubclass(v, Widget)
+            and v is not Widget
+            and getattr(v, "__module__", None) == module.__name__
+        ):
+            candidates.append(v)
+    unique = list({id(c): c for c in candidates}.values())
+    if len(unique) == 1:
+        return unique[0], None
+    if len(unique) > 1:
+        return None, "ambiguous_class"
+    return None, "no_widget_class"
+
+
+def validate_widget_source(
+    name: str, source: str,
+) -> tuple[type[Widget] | None, dict, str]:
+    """Compile `source` and run the §2 class-detection precedence WITHOUT
+    registering anything. Returns (cls, meta, "") on success, or
+    (None, {}, error_text) on failure. `error_text` is one of: a one-line
+    syntax error excerpt, "no_widget_class", "ambiguous_class", or another
+    short description. `meta` is the imported module's `__patchbai_widget__`
+    dict (or `{}` if absent) — used by `save_widget` to register description
+    and props_schema in the live registry.
+
+    Used by the `save_widget` MCP tool to validate orchestrator-supplied
+    source before committing it to ~/.config/patchbai/widgets/.
+    """
+    with tempfile.TemporaryDirectory() as td:
+        path = Path(td) / f"{name}.py"
+        try:
+            path.write_text(source, encoding="utf-8")
+        except OSError as e:
+            return None, {}, f"could not stage source for validation: {e}"
+
+        mod_name = f"_patchbai_validate_widget_{name}"
+        try:
+            spec = importlib.util.spec_from_file_location(mod_name, path)
+            assert spec is not None and spec.loader is not None
+            module = importlib.util.module_from_spec(spec)
+            sys.modules[mod_name] = module
+            try:
+                spec.loader.exec_module(module)
+            finally:
+                # Don't leak a module entry that points at a deleted tempdir.
+                sys.modules.pop(mod_name, None)
+        except Exception as e:
+            return None, {}, f"{type(e).__name__}: {e}"
+
+        meta = getattr(module, "__patchbai_widget__", {}) or {}
+        if not isinstance(meta, dict):
+            meta = {}
+        cls, err = _find_widget_class_in_module(module, meta, name)
+        if cls is None:
+            return None, {}, err or "no_widget_class"
+        return cls, meta, ""

patchbai/layout/registry.py

@@ -0,0 +1,69 @@
+from dataclasses import dataclass, field
+from typing import Literal
+
+from textual.widget import Widget
+
+
+class UnknownWidgetError(KeyError):
+    """Raised when a LayoutSpec references a widget name that is not registered."""
+
+
+WidgetSource = Literal["builtin", "local", "inline"]
+
+
+@dataclass(frozen=True)
+class WidgetInfo:
+    name: str
+    cls: type[Widget]
+    description: str = ""
+    props_schema: dict = field(default_factory=dict)
+    source: WidgetSource = "builtin"
+
+
+class WidgetRegistry:
+    """Maps widget-type strings (as used in LayoutSpec) to Textual classes,
+    plus optional metadata for the orchestrator's list_widgets tool.
+
+    Mode-C `register_custom_widget(name, source)` (which `exec`s code into an
+    isolated namespace) is intentionally NOT implemented in this plan — it
+    arrives in plan 6.
+    """
+
+    def __init__(self) -> None:
+        self._infos: dict[str, WidgetInfo] = {}
+
+    def register(
+        self,
+        name: str,
+        cls: type[Widget],
+        *,
+        description: str = "",
+        props_schema: dict | None = None,
+        source: WidgetSource = "builtin",
+    ) -> None:
+        self._infos[name] = WidgetInfo(
+            name=name, cls=cls,
+            description=description,
+            props_schema=dict(props_schema) if props_schema else {},
+            source=source,
+        )
+
+    def unregister(self, name: str) -> None:
+        """Remove a widget registration. No-op if `name` was never registered."""
+        self._infos.pop(name, None)
+
+    def get(self, name: str) -> type[Widget]:
+        if name not in self._infos:
+            raise UnknownWidgetError(name)
+        return self._infos[name].cls
+
+    def known(self) -> list[str]:
+        return list(self._infos.keys())
+
+    def describe(self, name: str) -> WidgetInfo:
+        if name not in self._infos:
+            raise KeyError(name)
+        return self._infos[name]
+
+    def describe_all(self) -> list[WidgetInfo]:
+        return sorted(self._infos.values(), key=lambda i: i.name)

patchbai/layout/spec.py

@@ -0,0 +1,104 @@
+from typing import Annotated, Literal, Union
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+
+class Panel(BaseModel):
+    """A leaf node — one widget instance."""
+    model_config = ConfigDict(extra="forbid")
+
+    id: str
+    widget: str
+    props: dict = Field(default_factory=dict)
+    size: str | None = None
+    title: str | None = None
+
+
+class Container(BaseModel):
+    """A non-leaf node — splits its area horizontally or vertically."""
+    model_config = ConfigDict(extra="forbid")
+
+    type: Literal["horizontal", "vertical"]
+    size: str | None = None
+    children: list["Node"] = Field(min_length=1)
+
+
+class Tabs(BaseModel):
+    """A tabbed leaf-container — each child is one widget reachable via a
+    per-panel tab strip. Each tab holds exactly one Panel; splits inside
+    a single tab are not allowed.
+
+    `active` is the panel id of the initial tab; when None, the first
+    child is the initial tab."""
+    model_config = ConfigDict(extra="forbid")
+
+    type: Literal["tabs"]
+    size: str | None = None
+    children: list[Panel] = Field(min_length=1)
+    active: str | None = None
+
+    @model_validator(mode="after")
+    def _active_must_match_a_child(self) -> "Tabs":
+        if self.active is not None:
+            ids = {p.id for p in self.children}
+            if self.active not in ids:
+                raise ValueError(
+                    f"Tabs.active={self.active!r} does not match any child panel id; "
+                    f"expected one of {sorted(ids)}"
+                )
+        return self
+
+
+# Discriminated union: Container and Tabs share the `children` shape but
+# differ on `type`. Pydantic v2 dispatches on the literal `type` value.
+# Panel has no `type` field and is matched by absence — placed last so
+# union resolution prefers the typed branches first.
+_TypedNode = Annotated[Union[Container, Tabs], Field(discriminator="type")]
+Node = Union[_TypedNode, Panel]
+Container.model_rebuild()
+
+
+class CustomWidget(BaseModel):
+    """A user/orchestrator-supplied Textual widget class."""
+    model_config = ConfigDict(extra="forbid")
+
+    name: str
+    source: str
+
+
+class LayoutSpec(BaseModel):
+    """Root of the layout description.
+
+    Validation invariant: at most one panel with widget='OrchestratorChat'
+    in `layout`. The "at least one chat across all tabs" half is enforced
+    by the Workspace model — a single LayoutSpec may have zero chats
+    (e.g., a logs-only tab).
+
+    The `focus` field names a panel id to receive keyboard focus on apply,
+    but is NOT validated against the tree at parse time — LayoutEngine.apply
+    silently no-ops if the id does not exist when the layout is mounted.
+    """
+    model_config = ConfigDict(extra="forbid")
+
+    version: int = 1
+    layout: Node
+    focus: str | None = None
+    custom_widgets: list[CustomWidget] = Field(default_factory=list)
+
+    @model_validator(mode="after")
+    def _at_most_one_orchestrator_chat(self) -> "LayoutSpec":
+        count = _count_orchestrator(self.layout)
+        if count > 1:
+            raise ValueError(
+                "LayoutSpec must contain at most one OrchestratorChat panel"
+            )
+        return self
+
+
+def _count_orchestrator(node: Node) -> int:
+    if isinstance(node, Panel):
+        return 1 if node.widget == "OrchestratorChat" else 0
+    if isinstance(node, Tabs):
+        return sum(1 for c in node.children if c.widget == "OrchestratorChat")
+    # Container
+    return sum(_count_orchestrator(c) for c in node.children)