thingsboard-cli 4.3.1.2__py3-none-any.whl

thingsboard_cli/core/interactive_pull/app.py

@@ -0,0 +1,1028 @@
+"""Textual app for the interactive pull picker.
+
+This module owns:
+
+* The :class:`PickerApp` Textual App (top-level UI lifecycle).
+* The single picker screen with a search input, filter-chip strip, a
+  stack of section :class:`SectionWidget` collapsibles, and a footer
+  hint.
+* Key bindings: Space toggles the focused row; ``a`` smart-toggles all
+  filtered rows; ``c`` clears the selection (with a confirm prompt);
+  ``m`` fetches a group's members and adds them to the selection; ``/``
+  focuses the search input; ``q`` quits (also confirms when there are
+  unsaved selections); Enter opens the :class:`ConfirmScreen` and exits
+  with the assembled ``internalIds`` list on accept.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, ClassVar
+
+from textual import on, work
+from textual.app import App, ComposeResult
+from textual.binding import Binding, BindingType
+from textual.containers import Horizontal, VerticalScroll
+from textual.reactive import reactive
+from textual.widgets import Collapsible, DataTable, Footer, Header, Input, Static
+from textual.widgets._data_table import CellDoesNotExist, RowKey
+
+from thingsboard_cli.core.interactive_pull.confirm import ConfirmScreen, DiscardConfirmScreen
+from thingsboard_cli.core.interactive_pull.formatting import (
+    customer_dfs_sort,
+    entity_row_to_cells,
+    group_row_to_cells,
+)
+from thingsboard_cli.core.interactive_pull.listing import resolve_root_owner
+from thingsboard_cli.core.interactive_pull.loader import (
+    LoaderResult,
+    fetch_group_members,
+    load_section_groups,
+    load_section_individuals,
+)
+from thingsboard_cli.core.interactive_pull.owner import OwnerResolver
+from thingsboard_cli.core.interactive_pull.rows import EntityRow, GroupRow, get_display_name
+from thingsboard_cli.core.interactive_pull.search import Query, parse_query, row_matches
+from thingsboard_cli.core.interactive_pull.sections import SECTION_ORDER, SectionMeta
+from thingsboard_cli.core.interactive_pull.state import SelectionState
+from thingsboard_cli.core.interactive_pull.theme import (
+    GLYPH_CHECK_OFF,
+    GLYPH_CHECK_ON,
+    GLYPH_SEARCH,
+    TB_PICKER_THEME,
+)
+
+if TYPE_CHECKING:
+    from thingsboard_cli.commands.pull import _PullOptions
+
+
+# Per-section DataTable column shape: (header_label, key, width-or-None).
+_SECTION_COLUMNS: dict[str, list[tuple[str, str, int | None]]] = {
+    "CUSTOMER": [("", "check", 3), ("Name", "name", None), ("ID", "id", None), ("Owner", "owner", None)],
+    "ROLE": [("", "check", 3), ("Name", "name", None), ("ID", "id", None), ("Owner", "owner", None)],
+    "DEVICE_PROFILE": [("", "check", 3), ("Name", "name", None), ("ID", "id", None)],
+    "ASSET_PROFILE": [("", "check", 3), ("Name", "name", None), ("ID", "id", None)],
+    "USER": [
+        ("", "check", 3),
+        ("Email", "email", None),
+        ("Name", "name", None),
+        ("ID", "id", None),
+        ("Owner", "owner", None),
+    ],
+    "DEVICE": [
+        ("", "check", 3),
+        ("Name", "name", None),
+        ("ID", "id", None),
+        ("Owner", "owner", None),
+        ("Profile", "profile", None),
+    ],
+    "ASSET": [
+        ("", "check", 3),
+        ("Name", "name", None),
+        ("ID", "id", None),
+        ("Owner", "owner", None),
+        ("Profile", "profile", None),
+    ],
+    "DASHBOARD": [("", "check", 3), ("Title", "title", None), ("ID", "id", None), ("Owner", "owner", None)],
+    "RULE_CHAIN": [("", "check", 3), ("Name", "name", None), ("ID", "id", None)],
+}
+
+# Groups DataTable shape (one for every section with groups). There is no
+# Members column: the group listing carries no member count and we don't make
+# a per-group call to fetch one.
+_GROUP_COLUMNS: list[tuple[str, str, int | None]] = [
+    ("", "check", 3),
+    ("Group", "name", None),
+    ("Owner", "owner", None),
+    ("Flags", "flags", None),
+]
+
+
+def _read(obj: Any, key: str) -> Any:
+    if isinstance(obj, dict):
+        return obj.get(key)
+    snake = key
+    if any(c.isupper() for c in key):
+        snake = "".join(("_" + c.lower()) if c.isupper() else c for c in key).lstrip("_")
+    return getattr(obj, snake, None) if hasattr(obj, snake) else getattr(obj, key, None)
+
+
+def _as_str(value: Any) -> str | None:
+    """Coerce tb-pe-client's pydantic field values (UUID, Enum, str) to a plain string.
+
+    StrEnum members satisfy ``isinstance(x, str)`` but ``str(x)`` yields
+    ``"Class.MEMBER"`` — using ``str.__str__`` returns the underlying string.
+    """
+    if value is None:
+        return None
+    if isinstance(value, str):
+        return str.__str__(value)
+    return str(value)
+
+
+def _ownership_from(obj: Any) -> tuple[str, str]:
+    owner = _read(obj, "ownerId") or _read(obj, "owner_id")
+    if owner is None:
+        return "TENANT", ""
+    owner_type = _as_str(_read(owner, "entityType") or _read(owner, "entity_type")) or "TENANT"
+    owner_id = _as_str(_read(owner, "id")) or ""
+    return owner_type, owner_id
+
+
+def _id_of(obj: Any) -> str | None:
+    id_obj = _read(obj, "id")
+    if id_obj is None:
+        return None
+    return _as_str(_read(id_obj, "id"))
+
+
+def _payload_of(obj: Any) -> dict[str, Any]:
+    """Flatten the row to a dict so :func:`get_display_name` can read fields."""
+    if isinstance(obj, dict):
+        return obj
+    out: dict[str, Any] = {}
+    for k in ("name", "title", "email", "type"):
+        v = getattr(obj, k, None)
+        if v is not None:
+            out[k] = v
+    return out
+
+
+def _make_rule_text(label: str, count: int, width: int = 50) -> str:
+    """Render a labeled rule like ` ─ Groups (3) ─────────────── `."""
+    head = f" ─ {label} ({count}) "
+    fill = max(width - len(head), 0)
+    return head + ("─" * fill)
+
+
+class _PickerSearch(Input):
+    """Search input with an Escape-to-clear binding."""
+
+    BINDINGS: ClassVar[list[BindingType]] = [
+        Binding("escape", "clear_search", "clear", show=False),
+    ]
+
+    def action_clear_search(self) -> None:
+        self.value = ""
+        self.can_focus = False
+        self.blur()
+
+
+class _PickerScroll(VerticalScroll):
+    """Section scroll container that lets ↑/↓ bubble up to the app.
+
+    A plain ``VerticalScroll`` binds the arrow keys to its own scroll
+    actions, which would swallow ↑/↓ before they reach the app's focus
+    navigation whenever focus sits on a section header. Disabling just the
+    vertical-scroll actions lets the keys fall through (Textual still
+    auto-scrolls the focused widget into view).
+    """
+
+    def check_action(self, action: str, parameters: tuple[object, ...]) -> bool | None:
+        # Returning False (not None) keeps the binding registered but disabled,
+        # so Textual skips it and the key bubbles up to the app's nav bindings
+        # (↑/↓ move focus; ←/→ collapse/expand the focused section).
+        return action not in ("scroll_up", "scroll_down", "scroll_left", "scroll_right")
+
+
+class _NavDataTable(DataTable):
+    """A ``DataTable`` that hands focus to the next/previous widget when the
+    cursor would step past the first/last row.
+
+    This is what makes ↑/↓ drive the whole picker: arrows move the row
+    cursor inside a table, and at a table's top/bottom edge they fall
+    through to the adjacent section header or table instead of stalling.
+    """
+
+    def action_cursor_down(self) -> None:
+        if self.cursor_row >= self.row_count - 1:
+            self.screen.focus_next()
+            return
+        super().action_cursor_down()
+
+    def action_cursor_up(self) -> None:
+        if self.cursor_row <= 0:
+            self.screen.focus_previous()
+            return
+        super().action_cursor_up()
+
+    def check_action(self, action: str, parameters: tuple[object, ...]) -> bool | None:
+        # Don't capture Enter for row-select — let it bubble to the app so the
+        # pull can be applied while a section's table is focused. Likewise let
+        # ← fall through (disabled-but-registered, like _PickerScroll) so the
+        # app's collapse-section binding fires from any row, not just the
+        # header. (Row cursor mode makes horizontal cursor moves a no-op
+        # anyway.)
+        return action not in ("select_cursor", "cursor_left")
+
+
+class SectionWidget(Collapsible):
+    """Per-section collapsible. Streams rows into ``DataTable`` children
+    on first expand.
+    """
+
+    state: reactive[str] = reactive("UNLOADED")  # UNLOADED | LOADING | LOADED | CAPPED | ERROR
+
+    def __init__(self, meta: SectionMeta) -> None:
+        super().__init__(title=meta.label, collapsed=True)
+        self.meta = meta
+        self._entity_rows: list[EntityRow] = []
+        self._group_rows: list[GroupRow] = []
+        # Caches the rows currently visible after filtering; rebuilt by
+        # ``_render_entity_rows`` / ``_render_group_rows`` on every filter pass.
+        self._visible_entity_rows_by_key: dict[str, EntityRow] = {}
+        self._visible_group_rows_by_key: dict[str, GroupRow] = {}
+        self._entity_table: DataTable | None = None
+        self._group_table: DataTable | None = None
+        self._status: Static | None = None
+        self._groups_subhead: Static | None = None
+        self._individuals_subhead: Static | None = None
+        # The initial ``section--unloaded`` class is applied by ``watch_state``
+        # post-mount (Textual reactives default to ``init=True``).
+
+    def compose(self) -> ComposeResult:
+        self._status = Static("", id=f"status-{self.meta.entity_type.lower()}", classes="status")
+        self._status.display = False
+        children: list[Static | DataTable] = [self._status]
+        if self.meta.supports_groups:
+            self._groups_subhead = Static(_make_rule_text("Groups", 0), classes="subhead rule")
+            self._groups_subhead.display = False
+            children.append(self._groups_subhead)
+            self._group_table = _NavDataTable(
+                id=f"groups-{self.meta.entity_type.lower()}",
+                cursor_type="row",
+                zebra_stripes=False,
+                show_header=True,
+            )
+            self._group_table.display = False
+            children.append(self._group_table)
+            self._individuals_subhead = Static(_make_rule_text("Entities", 0), classes="subhead rule")
+            self._individuals_subhead.display = False
+            children.append(self._individuals_subhead)
+        self._entity_table = _NavDataTable(
+            id=f"individuals-{self.meta.entity_type.lower()}",
+            cursor_type="row",
+            zebra_stripes=False,
+            show_header=True,
+        )
+        self._entity_table.display = False
+        children.append(self._entity_table)
+        yield self._title
+        yield Collapsible.Contents(*children)
+
+    def update_header_summary(self, selected: int, total: int, group_selected: int, group_total: int) -> None:
+        # Textual's Collapsible already renders its own ▶/▼ chevron next to the
+        # title, so we don't add one here.
+        parts: list[str] = [self.meta.label]
+        if selected or total:
+            parts.append(f"{selected}/{total}")
+        if self.meta.supports_groups and (group_selected or group_total):
+            parts.append(f"{group_selected}/{group_total} groups")
+        self.title = "  ·  ".join(parts)
+
+    def update_subheads(self) -> None:
+        if self._individuals_subhead is not None and self._entity_table is not None:
+            self._individuals_subhead.update(_make_rule_text("Entities", self._entity_table.row_count))
+        if self._groups_subhead is not None and self._group_table is not None:
+            self._groups_subhead.update(_make_rule_text("Groups", self._group_table.row_count))
+
+    def watch_state(self, _old: str, new: str) -> None:
+        for state in ("unloaded", "loading", "loaded", "capped", "error"):
+            self.remove_class(f"section--{state}")
+        self.add_class(f"section--{new.lower()}")
+
+
+class PickerApp(App[Any]):
+    """Top-level Textual app for the interactive picker.
+
+    Result is exposed on ``self.result`` after ``run()`` returns — either the
+    list of ``internalIds`` dicts to pull, or ``None`` on cancel.
+    """
+
+    BINDINGS: ClassVar[list[BindingType]] = [
+        Binding("q", "quit_picker", "quit"),
+        Binding("space", "toggle_focused", "toggle"),
+        Binding("enter", "confirm", "pull selected"),
+        Binding("c", "clear_all", "clear all"),
+        Binding("a", "smart_toggle", "select/deselect filtered"),
+        Binding("m", "expand_members", "add group members"),
+        Binding("slash,/", "focus_search", "search"),
+        # ↑/↓ move focus across headers and tables. A focused DataTable
+        # consumes them first for its own row cursor (and falls through at
+        # its edges via _NavDataTable); these fire when a header is focused.
+        Binding("down", "nav_down", "down", show=False),
+        Binding("up", "nav_up", "up", show=False),
+        # →/← expand/collapse the focused section (tree-style). They only act
+        # on a focused header; a focused table consumes them or the action
+        # no-ops.
+        Binding("right", "expand_focused_section", "open", show=False),
+        Binding("left", "collapse_focused_section", "close", show=False),
+    ]
+
+    CSS_PATH = "picker.tcss"
+
+    # The search input has no auto-focus; the user presses ``/`` to focus it.
+    # This keeps single-letter bindings (c, a, m, q, …) reachable on startup
+    # without going through Tab first.
+    AUTO_FOCUS = None
+
+    current_query: reactive[Query] = reactive(Query(owner=None, text="", server_search=None))
+
+    def __init__(
+        self,
+        *,
+        opts: _PullOptions,
+        solution_dir: Path,
+        client: Any,
+        profile_label: str | None = None,
+    ) -> None:
+        super().__init__()
+        # ``TB_PICKER_THEME`` resolves its background tokens to ``ansi_default``
+        # so the picker blends with the terminal's own background, but uses
+        # curated ANSI bright foreground colors for borders and accents
+        # (terminal blue can read poorly on dark schemes, so we avoid it).
+        # The theme setter resets ``ansi_color`` to False for any non-textual-ansi
+        # theme; explicitly flipping it back to True keeps the ``ansi_default``
+        # backgrounds actually transparent on screen.
+        self.register_theme(TB_PICKER_THEME)
+        self.theme = "tb-picker"
+        self.ansi_color = True
+        self.opts = opts
+        # The resolved profile name to show in the header/confirm screen. When
+        # the caller didn't pass one we fall back to the --profile value, then
+        # to a generic placeholder (see ``_profile_display``).
+        self._profile_label = profile_label
+        self.solution_dir = solution_dir
+        self.client = client
+        self.selection = SelectionState()
+        self.owner_resolver = OwnerResolver(client)
+        self._sections: dict[str, SectionWidget] = {}
+        self._chips_container: Horizontal | None = None
+        self.result: list[dict[str, str]] | None = None
+        # Ownership-hierarchy root for group listings, resolved once via
+        # get_user() on the first group-bearing section load.
+        self._root_owner: tuple[str, str] | None = None
+        # Owners to query for entity groups (tenant + every customer) and the
+        # cached customer records used to derive them — resolved once.
+        self._group_owners: list[tuple[str, str]] | None = None
+        self._all_customers: list[Any] | None = None
+
+    def compose(self) -> ComposeResult:
+        self.title = "tb pull · interactive"
+        self.sub_title = self._base_subtitle()
+        yield Header()
+        # The search input is hidden from Tab order so single-letter bindings
+        # (c, a, m, …) reach the app instead of being typed into the box. It
+        # becomes focusable only when the user explicitly presses ``/``.
+        search = _PickerSearch(
+            placeholder=f"{GLYPH_SEARCH}Search… (/ to focus, owner:<name>, server:<query>)",
+            id="search",
+        )
+        search.can_focus = False
+        yield search
+        self._chips_container = Horizontal(id="filter-chips", classes="filter-chips")
+        yield self._chips_container
+        scroll = _PickerScroll()
+        scroll.can_focus = False  # let Tab skip past the scroll container to section titles
+        with scroll:
+            for meta in SECTION_ORDER:
+                widget = SectionWidget(meta)
+                self._sections[meta.entity_type] = widget
+                yield widget
+        yield Footer()
+
+    def action_nav_down(self) -> None:
+        self.screen.focus_next()
+
+    def action_nav_up(self) -> None:
+        self.screen.focus_previous()
+
+    def _focused_header_section(self) -> SectionWidget | None:
+        """Return the SectionWidget whose header is focused, or None."""
+        for widget in self._sections.values():
+            if widget._title is self.focused:
+                return widget
+        return None
+
+    def action_expand_focused_section(self) -> None:
+        widget = self._focused_header_section()
+        if widget is not None:
+            widget.collapsed = False  # posts Collapsible.Expanded → loads on demand
+
+    def action_collapse_focused_section(self) -> None:
+        # Works whether the section header or one of its tables is focused, so
+        # ← closes a section from anywhere inside it. When collapsing from a
+        # table, move focus up to the header so the cursor isn't stranded on a
+        # now-hidden table.
+        widget = self._focused_header_section()
+        if widget is not None:
+            widget.collapsed = True
+            return
+        info = self._focused_section_and_table()
+        if info is not None:
+            widget = info[0]
+            widget.collapsed = True
+            widget._title.focus()
+
+    # -- Section expansion / loading -----------------------------------------
+
+    @on(Collapsible.Expanded)
+    async def _on_section_expanded(self, event: Collapsible.Expanded) -> None:
+        widget = event.collapsible
+        if not isinstance(widget, SectionWidget):
+            return
+        if widget.state in ("LOADING", "LOADED", "CAPPED"):
+            return
+        await self._load_section(widget)
+
+    async def expand_section_by_type(self, entity_type: str) -> None:
+        """Test helper — programmatically expand and load *entity_type*."""
+        widget = self._sections[entity_type]
+        widget.collapsed = False
+        await self._load_section(widget)
+
+    async def focus_row(self, entity_type: str, entity_id: str) -> None:
+        """Test helper — focus the row whose id matches *entity_id*."""
+        widget = self._sections[entity_type]
+        table = widget._entity_table
+        if table is None:
+            return
+        try:
+            row_index = table.get_row_index(entity_id)
+        except KeyError:
+            return
+        table.focus()
+        table.move_cursor(row=row_index)
+
+    async def focus_group_row(self, entity_type: str, group_id: str) -> None:
+        """Test helper — focus the group row whose id matches *group_id*."""
+        widget = self._sections[entity_type]
+        table = widget._group_table
+        if table is None:
+            return
+        try:
+            row_index = table.get_row_index(group_id)
+        except KeyError:
+            return
+        table.focus()
+        table.move_cursor(row=row_index)
+
+    def visible_row_ids(self, entity_type: str) -> set[str]:
+        """Test helper — set of entity ids currently visible in the section's individuals table."""
+        widget = self._sections.get(entity_type)
+        if widget is None or widget._entity_table is None:
+            return set()
+        return {key.value for key in widget._entity_table.rows if key.value is not None}
+
+    async def _ensure_root_owner(self) -> tuple[str, str]:
+        """Resolve and cache the ownership-hierarchy root (one get_user() call)."""
+        if self._root_owner is None:
+            loop = asyncio.get_running_loop()
+            self._root_owner = await loop.run_in_executor(None, resolve_root_owner, self.client)
+        return self._root_owner
+
+    async def _ensure_all_customers(self) -> list[Any]:
+        """Fetch and cache every customer once (used for group-owner enumeration)."""
+        if self._all_customers is None:
+            loop = asyncio.get_running_loop()
+            result = await loop.run_in_executor(None, load_section_individuals, self.client, "CUSTOMER")
+            self._all_customers = result.records
+            # Registering here means customer-owned group/entity rows resolve
+            # their owner paths without per-row get_customer_by_id calls.
+            self.owner_resolver.register_customers(self._all_customers)
+        return self._all_customers
+
+    async def _ensure_group_owners(self) -> list[tuple[str, str]]:
+        """Resolve and cache the owners to query for entity groups.
+
+        Entity groups have no cross-owner listing, so we enumerate the
+        ownership root (tenant or customer) plus every customer and query
+        each owner individually.
+        """
+        if self._group_owners is None:
+            root = await self._ensure_root_owner()
+            customers = await self._ensure_all_customers()
+            owners: list[tuple[str, str]] = [root]
+            for rec in customers:
+                cid = _id_of(rec)
+                if cid and cid != root[1]:
+                    owners.append(("CUSTOMER", cid))
+            self._group_owners = owners
+        return self._group_owners
+
+    async def _load_section(self, widget: SectionWidget) -> None:
+        widget.state = "LOADING"
+        if widget._status is not None:
+            widget._status.display = True
+            widget._status.update("[italic dim]Loading…[/]")
+
+        loop = asyncio.get_running_loop()
+        try:
+            indiv_result: LoaderResult = await loop.run_in_executor(
+                None,
+                load_section_individuals,
+                self.client,
+                widget.meta.entity_type,
+            )
+        except Exception as exc:
+            widget.state = "ERROR"
+            if widget._status is not None:
+                widget._status.display = True
+                widget._status.update(f"[red]Failed to load — {exc}[/]")
+            return
+
+        if widget.meta.entity_type == "CUSTOMER":
+            # Index customers in the owner resolver so subsequent sections
+            # can look up their paths cheaply, and reuse this list for
+            # group-owner enumeration (avoids a second customer fetch).
+            self.owner_resolver.register_customers(indiv_result.records)
+            if self._all_customers is None:
+                self._all_customers = indiv_result.records
+
+        group_result: LoaderResult | None = None
+        if widget.meta.supports_groups:
+            try:
+                owners = await self._ensure_group_owners()
+                group_result = await loop.run_in_executor(
+                    None,
+                    lambda: load_section_groups(
+                        self.client,
+                        widget.meta.entity_type,
+                        owners=owners,
+                    ),
+                )
+            except Exception as exc:
+                # Individuals already loaded — keep the section usable, but surface
+                # the group failure instead of silently showing an empty sub-area.
+                group_result = LoaderResult(records=[], total=0, capped=False)
+                self.notify(f"Failed to load {widget.meta.label} groups — {exc}", severity="error")
+
+        await self._render_section(widget, indiv_result, group_result)
+
+    def _build_entity_rows(self, widget: SectionWidget, indiv_result: LoaderResult) -> list[EntityRow]:
+        meta = widget.meta
+        entity_rows: list[EntityRow] = []
+        for rec in indiv_result.records:
+            entity_id = _id_of(rec)
+            if not entity_id:
+                continue
+            owner_type, owner_id = _ownership_from(rec)
+            owner_path = self.owner_resolver.path(owner_type, owner_id) if meta.supports_ownership else None
+            payload = _payload_of(rec)
+            display = get_display_name(meta.entity_type, payload)
+            secondary = ""
+            if meta.entity_type in ("DEVICE", "ASSET"):
+                t = payload.get("type")
+                if t:
+                    secondary = f"profile: {t}"
+            elif meta.entity_type == "USER":
+                first = _as_str(_read(rec, "firstName")) or ""
+                last = _as_str(_read(rec, "lastName")) or ""
+                secondary = " ".join(p for p in (first, last) if p)
+            indent = len(owner_path or ()) if meta.entity_type == "CUSTOMER" else 0
+            entity_rows.append(
+                EntityRow(
+                    entity_type=meta.entity_type,
+                    entity_id=entity_id,
+                    display_name=display,
+                    secondary=secondary,
+                    owner_path=owner_path,
+                    indent_depth=indent,
+                )
+            )
+        if meta.entity_type == "CUSTOMER":
+            entity_rows = customer_dfs_sort(entity_rows)
+        return entity_rows
+
+    def _build_group_rows(self, widget: SectionWidget, group_result: LoaderResult) -> list[GroupRow]:
+        meta = widget.meta
+        group_rows: list[GroupRow] = []
+        for rec in group_result.records:
+            gid = _id_of(rec)
+            if not gid:
+                continue
+            owner_type, owner_id = _ownership_from(rec)
+            owner_path = self.owner_resolver.path(owner_type, owner_id)
+            display = get_display_name("ENTITY_GROUP", _payload_of(rec))
+            is_group_all = bool(_read(rec, "groupAll") or _read(rec, "group_all"))
+            group_rows.append(
+                GroupRow(
+                    entity_type="ENTITY_GROUP",
+                    entity_id=gid,
+                    display_name=display,
+                    member_type=meta.entity_type,
+                    owner_path=owner_path,
+                    is_system=is_group_all,
+                )
+            )
+        return group_rows
+
+    def _ensure_entity_columns(self, table: DataTable, meta: SectionMeta) -> None:
+        if table.columns:
+            return
+        for header, key, width in _SECTION_COLUMNS[meta.entity_type]:
+            table.add_column(header, key=key, width=width)
+
+    def _ensure_group_columns(self, table: DataTable) -> None:
+        if table.columns:
+            return
+        for header, key, width in _GROUP_COLUMNS:
+            table.add_column(header, key=key, width=width)
+
+    def _entity_check_cell(self, row: EntityRow) -> str:
+        return GLYPH_CHECK_ON if self.selection.is_selected(row.entity_type, row.entity_id) else GLYPH_CHECK_OFF
+
+    def _group_check_cell(self, row: GroupRow) -> str:
+        return GLYPH_CHECK_ON if self.selection.is_selected("ENTITY_GROUP", row.entity_id) else GLYPH_CHECK_OFF
+
+    def _render_entity_rows(self, widget: SectionWidget, rows: list[EntityRow]) -> None:
+        table = widget._entity_table
+        assert table is not None
+        table.clear()
+        widget._visible_entity_rows_by_key = {}
+        for row in rows:
+            cells = entity_row_to_cells(row, widget.meta)
+            cells[0] = self._entity_check_cell(row)
+            table.add_row(*cells, key=row.entity_id)
+            widget._visible_entity_rows_by_key[row.entity_id] = row
+
+    def _render_group_rows(self, widget: SectionWidget, rows: list[GroupRow]) -> None:
+        table = widget._group_table
+        assert table is not None
+        table.clear()
+        widget._visible_group_rows_by_key = {}
+        for row in rows:
+            cells = group_row_to_cells(row)
+            cells[0] = self._group_check_cell(row)
+            table.add_row(*cells, key=row.entity_id)
+            widget._visible_group_rows_by_key[row.entity_id] = row
+
+    async def _render_section(
+        self,
+        widget: SectionWidget,
+        indiv_result: LoaderResult,
+        group_result: LoaderResult | None,
+    ) -> None:
+        meta = widget.meta
+
+        entity_rows = self._build_entity_rows(widget, indiv_result)
+        widget._entity_rows = entity_rows
+        assert widget._entity_table is not None
+        self._ensure_entity_columns(widget._entity_table, meta)
+        # Render through the active query so a section expanded *after* a filter
+        # was typed honors it — otherwise it would show every row unfiltered.
+        self._render_entity_rows(widget, self._filter_entity_rows(entity_rows))
+
+        if meta.supports_groups and group_result is not None:
+            group_rows = self._build_group_rows(widget, group_result)
+            widget._group_rows = group_rows
+            assert widget._group_table is not None
+            self._ensure_group_columns(widget._group_table)
+            self._render_group_rows(widget, self._filter_group_rows(group_rows))
+
+        widget.state = "CAPPED" if indiv_result.capped else "LOADED"
+        self._sync_section_chrome(widget, indiv_result)
+        self._refresh_header(widget)
+
+    def _sync_section_chrome(self, widget: SectionWidget, indiv_result: LoaderResult) -> None:
+        if widget._entity_table is not None:
+            widget._entity_table.display = True
+        if widget.meta.supports_groups:
+            if widget._group_table is not None:
+                widget._group_table.display = widget._group_table.row_count > 0
+            if widget._groups_subhead is not None:
+                widget._groups_subhead.display = widget._group_table is not None and widget._group_table.row_count > 0
+            if widget._individuals_subhead is not None:
+                widget._individuals_subhead.display = True
+        widget.update_subheads()
+        if widget._status is None:
+            return
+        if widget.state == "CAPPED":
+            widget._status.display = True
+            widget._status.update(
+                f"[yellow]{indiv_result.total} entities — too many. Press [bold]/[/] then [italic]server:<query>[/].[/]"
+            )
+        else:
+            widget._status.display = False
+            widget._status.update("")
+
+    def _refresh_header(self, widget: SectionWidget) -> None:
+        selected = sum(1 for r in widget._entity_rows if self.selection.is_selected(r.entity_type, r.entity_id))
+        total = len(widget._entity_rows)
+        group_total = len(widget._group_rows)
+        group_selected = sum(1 for r in widget._group_rows if self.selection.is_selected("ENTITY_GROUP", r.entity_id))
+        widget.update_header_summary(selected, total, group_selected, group_total)
+        self._refresh_header_subtitle()
+
+    def _profile_display(self) -> str:
+        """Profile name to show: explicit label, else --profile, else 'default'."""
+        return self._profile_label or getattr(self.opts, "profile", None) or "default"
+
+    def _base_subtitle(self) -> str:
+        return f"profile: {self._profile_display()} · solution: {self.solution_dir.name}"
+
+    def _refresh_header_subtitle(self) -> None:
+        base = self._base_subtitle()
+        n = self.selection.total_count()
+        self.sub_title = f"{base} · {n} selected" if n else base
+
+    # -- Actions -------------------------------------------------------------
+
+    def _focused_section_and_table(self) -> tuple[SectionWidget, DataTable, bool] | None:
+        """Return (widget, table, is_group) for the currently-focused table, or None."""
+        focused = self.focused
+        if not isinstance(focused, DataTable):
+            return None
+        for widget in self._sections.values():
+            if focused is widget._entity_table:
+                return widget, focused, False
+            if focused is widget._group_table:
+                return widget, focused, True
+        return None
+
+    @staticmethod
+    def _cursor_row_key(table: DataTable) -> RowKey | None:
+        if table.row_count == 0:
+            return None
+        try:
+            return table.coordinate_to_cell_key(table.cursor_coordinate).row_key
+        except CellDoesNotExist:
+            return None
+
+    def action_toggle_focused(self) -> None:
+        info = self._focused_section_and_table()
+        if info is None:
+            return
+        widget, table, is_group = info
+        row_key = self._cursor_row_key(table)
+        if row_key is None or row_key.value is None:
+            return
+        if is_group:
+            row = widget._visible_group_rows_by_key.get(row_key.value)
+            if row is None:
+                return
+            self.selection.toggle_group(row.member_type, row.entity_id)
+            self._refresh_group_row(widget, row, row_key)
+        else:
+            erow = widget._visible_entity_rows_by_key.get(row_key.value)
+            if erow is None:
+                return
+            self.selection.toggle(erow.entity_type, erow.entity_id)
+            table.update_cell(row_key, "check", self._entity_check_cell(erow))
+        self._refresh_header(widget)
+
+    def _refresh_group_row(self, widget: SectionWidget, row: GroupRow, row_key: RowKey) -> None:
+        table = widget._group_table
+        if table is None:
+            return
+        table.update_cell(row_key, "check", self._group_check_cell(row))
+
+    def _refresh_visible_check_cells(self, widget: SectionWidget, *, group: bool) -> None:
+        if group:
+            table = widget._group_table
+            if table is None:
+                return
+            for key in list(table.rows):
+                if key.value is None:
+                    continue
+                row = widget._visible_group_rows_by_key.get(key.value)
+                if row is None:
+                    continue
+                self._refresh_group_row(widget, row, key)
+            return
+        table = widget._entity_table
+        if table is None:
+            return
+        for key in list(table.rows):
+            if key.value is None:
+                continue
+            erow = widget._visible_entity_rows_by_key.get(key.value)
+            if erow is None:
+                continue
+            table.update_cell(key, "check", self._entity_check_cell(erow))
+
+    @work
+    async def action_quit_picker(self) -> None:
+        if self.selection.total_count() == 0:
+            self.result = None
+            self.exit()
+            return
+        confirmed = await self.push_screen_wait(DiscardConfirmScreen(count=self.selection.total_count()))
+        if confirmed:
+            self.result = None
+            self.exit()
+
+    @work
+    async def action_clear_all(self) -> None:
+        if self.selection.total_count() == 0:
+            return
+        # Distinct heading from the quit-discard modal so 'c' isn't mistaken
+        # for 'q' — clearing keeps the picker open, it doesn't exit.
+        confirmed = await self.push_screen_wait(
+            DiscardConfirmScreen(
+                count=self.selection.total_count(),
+                heading="Clear all selections?",
+                confirm_label="clear",
+            )
+        )
+        if confirmed:
+            self.selection.clear_all()
+            for widget in self._sections.values():
+                self._refresh_visible_check_cells(widget, group=False)
+                self._refresh_visible_check_cells(widget, group=True)
+                self._refresh_header(widget)
+
+    def action_smart_toggle(self) -> None:
+        info = self._focused_section_and_table()
+        if info is None:
+            return
+        widget, _table, is_group = info
+        if is_group:
+            visible_groups = [
+                g
+                for g in widget._group_rows
+                if row_matches(self.current_query, display_name=g.display_name, owner_path=g.owner_path)
+            ]
+            if not visible_groups:
+                return
+            all_selected = all(self.selection.is_selected("ENTITY_GROUP", g.entity_id) for g in visible_groups)
+            for g in visible_groups:
+                is_selected = self.selection.is_selected("ENTITY_GROUP", g.entity_id)
+                if (not all_selected and not is_selected) or (all_selected and is_selected):
+                    self.selection.toggle_group(g.member_type, g.entity_id)
+            self._refresh_visible_check_cells(widget, group=True)
+            self._refresh_header(widget)
+            return
+        visible_entities = [
+            r
+            for r in widget._entity_rows
+            if row_matches(self.current_query, display_name=r.display_name, owner_path=r.owner_path)
+        ]
+        if not visible_entities:
+            return
+        all_selected = all(self.selection.is_selected(r.entity_type, r.entity_id) for r in visible_entities)
+        for r in visible_entities:
+            self.selection.set_selected(r.entity_type, r.entity_id, not all_selected)
+        self._refresh_visible_check_cells(widget, group=False)
+        self._refresh_header(widget)
+
+    async def action_expand_members(self) -> None:
+        info = self._focused_section_and_table()
+        if info is None or not info[2]:
+            self.notify("Press m while focused on a group row")
+            return
+        widget, table, _is_group = info
+        row_key = self._cursor_row_key(table)
+        if row_key is None or row_key.value is None:
+            return
+        row = widget._visible_group_rows_by_key.get(row_key.value)
+        if row is None:
+            return
+        if self.selection.members_already_expanded(row.entity_id):
+            self.notify(f"Already added the members of '{row.display_name}'.")
+            return
+        loop = asyncio.get_running_loop()
+        try:
+            members = await loop.run_in_executor(None, fetch_group_members, self.client, row.entity_id)
+        except Exception as exc:
+            self.notify(f"Failed to load members of '{row.display_name}' — {exc}", severity="error")
+            return
+        # Selecting the group's members implies the group itself is wanted, so
+        # tick the group row too (recording its member type for the confirm
+        # rollup). Pulling members without the group wrapper rarely makes sense.
+        if not self.selection.is_selected("ENTITY_GROUP", row.entity_id):
+            self.selection.toggle_group(row.member_type, row.entity_id)
+        for m in members.refs:
+            self.selection.set_selected(m["entityType"], m["id"], True)
+        # Mark the group resolved whether or not it had members: an empty group
+        # has nothing left to pull, so the confirm screen must not warn that its
+        # members were skipped, and a repeat 'm' is correctly a no-op.
+        self.selection.mark_members_expanded(row.entity_id)
+        if not members.refs:
+            self.notify(f"'{row.display_name}' has no members.")
+        elif members.truncated:
+            self.notify(
+                f"'{row.display_name}' has {members.total} members — added the first {len(members.refs)}. "
+                "Narrow with search to reach the rest.",
+                severity="warning",
+            )
+        else:
+            self.notify(f"Added {len(members.refs)} members of '{row.display_name}'.")
+        # Refresh visible rows in every section so member ticks paint.
+        for w in self._sections.values():
+            self._refresh_visible_check_cells(w, group=False)
+            self._refresh_visible_check_cells(w, group=True)
+            self._refresh_header(w)
+
+    @work
+    async def action_confirm(self) -> None:
+        if len(self.screen_stack) > 1:
+            return  # a modal (confirm/discard) is already open
+        if self.selection.total_count() == 0:
+            self.notify("Nothing selected — pick at least one entity.")
+            return
+        confirmed = await self.push_screen_wait(
+            ConfirmScreen(
+                self.selection,
+                self._profile_display(),
+                self.solution_dir.name,
+                dry_run=getattr(self.opts, "dry_run", False),
+            )
+        )
+        if confirmed:
+            self.result = self.selection.build_internal_ids()
+            self.exit()
+
+    def action_focus_search(self) -> None:
+        search = self.query_one("#search", Input)
+        # Re-enable focus (compose() opted the input out of the Tab order so
+        # single-letter bindings reach the app on startup).
+        search.can_focus = True
+        search.focus()
+
+    # -- Search filtering ----------------------------------------------------
+
+    @on(Input.Changed, "#search")
+    def _on_search_changed(self, event: Input.Changed) -> None:
+        self.current_query = parse_query(event.value)
+        self._apply_filter_to_all_sections()
+        self._update_filter_chips()
+        self._refresh_header_subtitle()
+
+    @on(Input.Submitted, "#search")
+    async def _on_search_submitted(self, event: Input.Submitted) -> None:
+        query = parse_query(event.value)
+        if query.server_search is None:
+            return
+        target = self._focused_section() or self._first_loaded_section()
+        if target is None:
+            self.notify("Expand a section first, then press / server:<query>")
+            return
+        loop = asyncio.get_running_loop()
+        try:
+            result = await loop.run_in_executor(
+                None,
+                lambda: load_section_individuals(
+                    self.client,
+                    target.meta.entity_type,
+                    text_search=query.server_search,
+                ),
+            )
+        except Exception as exc:
+            self.notify(f"Server search failed: {exc}", severity="error")
+            return
+        await self._render_section(target, result, None)
+
+    def _focused_section(self) -> SectionWidget | None:
+        info = self._focused_section_and_table()
+        return info[0] if info is not None else None
+
+    def _first_loaded_section(self) -> SectionWidget | None:
+        for widget in self._sections.values():
+            if widget.state in ("LOADED", "CAPPED"):
+                return widget
+        return None
+
+    def _filter_entity_rows(self, rows: list[EntityRow]) -> list[EntityRow]:
+        return [
+            r for r in rows if row_matches(self.current_query, display_name=r.display_name, owner_path=r.owner_path)
+        ]
+
+    def _filter_group_rows(self, rows: list[GroupRow]) -> list[GroupRow]:
+        return [
+            g for g in rows if row_matches(self.current_query, display_name=g.display_name, owner_path=g.owner_path)
+        ]
+
+    def _apply_filter_to_all_sections(self) -> None:
+        for widget in self._sections.values():
+            if widget._entity_table is None:
+                continue
+            self._ensure_entity_columns(widget._entity_table, widget.meta)
+            self._render_entity_rows(widget, self._filter_entity_rows(widget._entity_rows))
+            if widget._group_table is not None:
+                self._ensure_group_columns(widget._group_table)
+                self._render_group_rows(widget, self._filter_group_rows(widget._group_rows))
+                if widget._groups_subhead is not None:
+                    widget._groups_subhead.display = widget._group_table.row_count > 0
+                widget._group_table.display = widget._group_table.row_count > 0
+            widget.update_subheads()
+            self._refresh_header(widget)
+
+    def _update_filter_chips(self) -> None:
+        if self._chips_container is None or not self._chips_container.is_mounted:
+            return
+        query = self.current_query
+        has_filters = bool(query.owner or query.server_search)
+        self._chips_container.set_class(has_filters, "filters-active")
+        self._chips_container.remove_children()
+        if not has_filters:
+            return
+        if query.owner:
+            self._chips_container.mount(Static(f"owner: {query.owner}", classes="chip chip--owner"))
+        if query.server_search:
+            self._chips_container.mount(Static(f"server: {query.server_search}", classes="chip chip--server"))
+        self._chips_container.mount(Static("esc to clear", classes="hint"))
+
+
+__all__ = ["PickerApp", "SectionWidget"]