tau-coding-agent 0.1.0__py3-none-any.whl

tau/tui/components/select_list.py

@@ -0,0 +1,222 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable, Generic, TypeVar, TYPE_CHECKING
+
+from tau.tui.ansi import visible_width
+from tau.tui.component import Component
+from tau.tui.fuzzy import fuzzy_filter
+from tau.tui.input import InputEvent, KeyEvent
+from tau.tui.keybindings import get_keybindings
+
+if TYPE_CHECKING:
+    from tau.tui.theme import SelectListTheme
+
+T = TypeVar("T")
+
+
+@dataclass
+class SelectItem(Generic[T]):
+    """A single row in a SelectList."""
+    label:       str
+    description: str = ""
+    value:       T | None = None   # type: ignore[assignment]
+
+
+class SelectList(Component, Generic[T]):
+    """
+    Filterable, scrollable list of SelectItem rows.
+
+    - Fuzzy-filters items as `query` changes.
+    - Arrow keys / ctrl+p / ctrl+n navigate selection.
+    - Enter / Tab fires the on_confirm callback.
+    - Escape fires on_dismiss.
+    - Shows a scroll indicator when items overflow the viewport.
+
+    Usage::
+
+        lst = SelectList(items, max_visible=5, theme=theme.select)
+        lst.set_query(current_input)
+        lst.on_confirm(lambda item: ...)
+        lines = lst.render(width)
+    """
+
+    def __init__(
+        self,
+        items: list[SelectItem[T]] | None = None,
+        max_visible: int = 5,
+        theme: SelectListTheme | None = None,
+    ) -> None:
+        self._all_items:    list[SelectItem[T]] = items or []
+        self._filtered:     list[SelectItem[T]] = list(self._all_items)
+        self._max_visible   = max(1, max_visible)
+        self._selected      = 0
+        self._scroll_offset = 0
+        self._query         = ""
+        self._on_confirm:  Callable[[SelectItem[T]], None] | None = None
+        self._on_dismiss:  Callable[[], None] | None = None
+
+        from tau.tui.theme import SelectListTheme as _ST
+        self._theme = theme or _ST()
+
+    # -------------------------------------------------------------------------
+    # Public API
+    # -------------------------------------------------------------------------
+
+    @property
+    def active(self) -> bool:
+        return bool(self._filtered)
+
+    @property
+    def selected_item(self) -> SelectItem[T] | None:
+        if not self._filtered:
+            return None
+        return self._filtered[self._selected]
+
+    @property
+    def line_count(self) -> int:
+        return min(self._max_visible, len(self._filtered))
+
+    def set_items(self, items: list[SelectItem[T]]) -> None:
+        self._all_items = items
+        self._apply_filter()
+
+    def set_query(self, query: str) -> None:
+        if query == self._query:
+            return
+        self._query = query
+        self._apply_filter()
+
+    def set_theme(self, theme: SelectListTheme) -> None:
+        self._theme = theme
+
+    def on_confirm(self, cb: Callable[[SelectItem[T]], None]) -> None:
+        self._on_confirm = cb
+
+    def on_dismiss(self, cb: Callable[[], None]) -> None:
+        self._on_dismiss = cb
+
+    def move_up(self) -> None:
+        if self._filtered:
+            self._selected = (self._selected - 1) % len(self._filtered)
+            self._clamp_scroll()
+
+    def move_down(self) -> None:
+        if self._filtered:
+            self._selected = (self._selected + 1) % len(self._filtered)
+            self._clamp_scroll()
+
+    # -------------------------------------------------------------------------
+    # Component
+    # -------------------------------------------------------------------------
+
+    def render(self, width: int) -> list[str]:
+        t = self._theme
+        items = self._filtered
+
+        if not items:
+            return [t.empty("  no matches")]
+
+        count   = len(items)
+        visible = min(self._max_visible, count)
+
+        # Keep scroll window so selected stays in view
+        self._clamp_scroll()
+        start = self._scroll_offset
+
+        # Label column width: widest label in visible slice (min 8, max ~40% of width)
+        label_w = max(8, min(
+            max(len(it.label) for it in items[start:start + visible]),
+            width // 2,
+        ))
+        desc_w = max(0, width - label_w - 3)   # 3 = "  " indent + " " gap
+
+        lines: list[str] = []
+
+        # Scroll-up indicator
+        if start > 0:
+            lines.append(t.indicator(f"  ↑ {start} more"))
+
+        for i in range(start, start + visible):
+            item  = items[i]
+            is_sel = i == self._selected
+
+            label = item.label[:label_w].ljust(label_w)
+            desc  = (item.description[:desc_w] if desc_w > 0 else "")
+
+            if is_sel:
+                row = "  " + t.selected_label(label) + " " + t.selected_desc(desc)
+                if t.selected_bg:
+                    # Fill to full width and apply background
+                    vw   = visible_width(row)
+                    fill = max(0, width - vw)
+                    row  = t.selected_bg(row + " " * fill)
+            else:
+                row = "  " + t.normal_label(label) + " " + t.normal_desc(desc)
+
+            lines.append(row)
+
+        # Scroll-down indicator
+        remaining = count - (start + visible)
+        if remaining > 0:
+            lines.append(t.indicator(f"  ↓ {remaining} more"))
+
+        return lines
+
+    def handle_input(self, event: InputEvent) -> bool:
+        if not isinstance(event, KeyEvent):
+            return False
+
+        kb = get_keybindings()
+
+        if kb.matches(event, "tui.select.up"):
+            self.move_up()
+            return True
+
+        if kb.matches(event, "tui.select.down"):
+            self.move_down()
+            return True
+
+        if kb.matches(event, "tui.select.confirm"):
+            item = self.selected_item
+            if item is not None and self._on_confirm is not None:
+                self._on_confirm(item)
+            return True
+
+        if kb.matches(event, "tui.select.dismiss"):
+            if self._on_dismiss is not None:
+                self._on_dismiss()
+            return True
+
+        return False
+
+    # -------------------------------------------------------------------------
+    # Internal
+    # -------------------------------------------------------------------------
+
+    def _apply_filter(self) -> None:
+        if not self._query:
+            self._filtered = list(self._all_items)
+        else:
+            self._filtered = fuzzy_filter(
+                self._all_items,
+                self._query,
+                lambda item: item.label + " " + item.description,
+            )
+        # Clamp selection to new list length
+        if self._filtered:
+            self._selected = min(self._selected, len(self._filtered) - 1)
+        else:
+            self._selected = 0
+        self._scroll_offset = 0
+
+    def _clamp_scroll(self) -> None:
+        count   = len(self._filtered)
+        visible = min(self._max_visible, count)
+        # selected must be in [scroll_offset, scroll_offset + visible)
+        if self._selected < self._scroll_offset:
+            self._scroll_offset = self._selected
+        elif self._selected >= self._scroll_offset + visible:
+            self._scroll_offset = self._selected - visible + 1
+        # ensure scroll_offset valid
+        self._scroll_offset = max(0, min(self._scroll_offset, max(0, count - visible)))

tau/tui/components/settings_modal.py

@@ -0,0 +1,274 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Callable
+
+from tau.tui.ansi import RESET, BOLD, DIM, BRIGHT_BLACK, BRIGHT_WHITE
+
+
+@dataclass
+class SettingItem:
+    id: str
+    label: str
+    current_value: str
+    description: str = ""
+    values: list[str] = field(default_factory=list)
+    submenu_items: list[str] = field(default_factory=list)
+    submenu_title: str = ""
+    text_input: bool = False
+    submenu_settings: list["SettingItem"] = field(default_factory=list)
+    submenu_on_change: "Callable[[str, str], None] | None" = None
+
+
+class SettingsModal:
+    """Interactive settings list.
+
+    - Up/Down  navigate rows
+    - Enter/Space  cycle value, open submenu/sub-panel, or enter text-edit mode
+    - Escape  cancel text-edit / close submenu / close modal
+    - Type to fuzzy-search (or type into the edit buffer when editing)
+    - Backspace removes last search char (or last edit char when editing)
+    """
+
+    def __init__(
+        self,
+        items: list[SettingItem],
+        on_change: Callable[[str, str], None],
+        max_visible: int = 10,
+        title: str = "",
+    ) -> None:
+        self._all_items = items
+        self._filtered: list[SettingItem] = list(items)
+        self._on_change = on_change
+        self._max_visible = max_visible
+        self._title = title
+        self._selected = 0
+        self._search = ""
+
+        # Submenu state — either a ListModal (for submenu_items) or a nested SettingsModal
+        self._submenu: object | None = None
+        self._submenu_id: str | None = None
+
+        # Inline text-edit state
+        self._editing = False
+        self._edit_buffer = ""
+        self._edit_id: str | None = None
+
+    # ── Public state ──────────────────────────────────────────────────────────
+
+    @property
+    def in_submenu(self) -> bool:
+        return self._submenu is not None or self._editing
+
+    # ── Navigation ────────────────────────────────────────────────────────────
+
+    def move_up(self) -> None:
+        if self._editing:
+            return
+        if self._submenu is not None:
+            self._submenu.move_up()  # type: ignore[attr-defined]
+        elif self._filtered:
+            self._selected = (self._selected - 1) % len(self._filtered)
+
+    def move_down(self) -> None:
+        if self._editing:
+            return
+        if self._submenu is not None:
+            self._submenu.move_down()  # type: ignore[attr-defined]
+        elif self._filtered:
+            self._selected = (self._selected + 1) % len(self._filtered)
+
+    def activate(self) -> None:
+        """Enter/Space: confirm edit, activate submenu item, cycle value, or open sub-panel."""
+        if self._editing:
+            self._confirm_edit()
+            return
+
+        if self._submenu is not None:
+            if isinstance(self._submenu, SettingsModal):
+                self._submenu.activate()
+            else:
+                # ListModal: pick selected value and close
+                val = self._submenu.selected_value()  # type: ignore[attr-defined]
+                if val is not None and self._submenu_id is not None:
+                    self._apply_value(self._submenu_id, val)
+                self._submenu = None
+                self._submenu_id = None
+            return
+
+        if not self._filtered:
+            return
+
+        item = self._filtered[self._selected]
+
+        if item.submenu_settings:
+            self._submenu = SettingsModal(
+                item.submenu_settings,
+                item.submenu_on_change or self._on_change,
+                title=item.submenu_title or item.label,
+            )
+            self._submenu_id = item.id
+        elif item.submenu_items:
+            from tau.tui.components.modal import ListModal
+            self._submenu = ListModal(
+                item.submenu_items,
+                item.current_value,
+                item.submenu_title or item.label,
+                item.description,
+            )
+            self._submenu_id = item.id
+        elif item.text_input:
+            self._editing = True
+            self._edit_buffer = item.current_value
+            self._edit_id = item.id
+        elif item.values:
+            try:
+                idx = item.values.index(item.current_value)
+                new_val = item.values[(idx + 1) % len(item.values)]
+            except ValueError:
+                new_val = item.values[0]
+            self._apply_value(item.id, new_val)
+
+    def cancel_submenu(self) -> None:
+        if self._editing:
+            self._editing = False
+            self._edit_buffer = ""
+            self._edit_id = None
+        elif isinstance(self._submenu, SettingsModal) and self._submenu.in_submenu:
+            # Delegate Escape inward so nested edit/submenu closes first
+            self._submenu.cancel_submenu()
+        else:
+            self._submenu = None
+            self._submenu_id = None
+
+    # ── Search / text-edit input ──────────────────────────────────────────────
+
+    def append_search(self, ch: str) -> None:
+        if self._editing:
+            self._edit_buffer += ch
+            return
+        if isinstance(self._submenu, SettingsModal):
+            self._submenu.append_search(ch)
+            return
+        if self._submenu is not None:
+            return
+        self._search += ch
+        self._refilter()
+
+    def backspace_search(self) -> None:
+        if self._editing:
+            self._edit_buffer = self._edit_buffer[:-1]
+            return
+        if isinstance(self._submenu, SettingsModal):
+            self._submenu.backspace_search()
+            return
+        if self._submenu is not None:
+            return
+        if self._search:
+            self._search = self._search[:-1]
+            self._refilter()
+
+    # ── Render ────────────────────────────────────────────────────────────────
+
+    def render(self, width: int) -> list[str]:
+        if self._submenu is not None:
+            return self._submenu.render(width)  # type: ignore[attr-defined]
+
+        divider = BRIGHT_BLACK + "─" * width + RESET
+        lines: list[str] = []
+
+        if self._title:
+            lines.append(f"  {BOLD}{self._title}{RESET}")
+            lines.append(divider)
+
+        if self._editing:
+            lines.append(f"  {DIM}editing — enter to confirm, esc to cancel{RESET}")
+        elif self._search:
+            lines.append(f"  {DIM}/{RESET}{self._search}█")
+        else:
+            lines.append(f"  {DIM}type to search…{RESET}")
+        lines.append(divider)
+
+        if not self._filtered:
+            lines.append(f"  {DIM}No matching settings{RESET}")
+        else:
+            max_label = min(28, max(len(i.label) for i in self._filtered))
+            count = len(self._filtered)
+            visible = min(self._max_visible, count)
+            start = max(0, min(self._selected - visible // 2, count - visible))
+
+            if start > 0:
+                lines.append(f"  {DIM}↑ {start} more{RESET}")
+
+            for i in range(start, min(start + visible, count)):
+                item = self._filtered[i]
+                is_sel = i == self._selected
+                label_padded = item.label.ljust(max_label)
+                has_submenu = bool(item.submenu_items or item.submenu_settings)
+
+                if is_sel and self._editing:
+                    val_display = self._edit_buffer + "\033[7m \033[27m"
+                    row = (
+                        f"  {BOLD}{BRIGHT_WHITE}→ {label_padded}{RESET}"
+                        f"  {BRIGHT_WHITE}{val_display}{RESET}"
+                    )
+                else:
+                    val_display = (item.current_value.replace("_", " ") + " ▸") if has_submenu else item.current_value.replace("_", " ")
+                    if is_sel:
+                        row = (
+                            f"  {BOLD}{BRIGHT_WHITE}→ {label_padded}{RESET}"
+                            f"  {BRIGHT_WHITE}{val_display}{RESET}"
+                        )
+                    else:
+                        row = f"    {DIM}{label_padded}{RESET}  {val_display}"
+                lines.append(row)
+
+            remaining = count - (start + visible)
+            if remaining > 0:
+                lines.append(f"  {DIM}↓ {remaining} more{RESET}")
+
+        lines.append(divider)
+        desc = ""
+        if self._filtered and 0 <= self._selected < len(self._filtered):
+            desc = self._filtered[self._selected].description
+        lines.append(f"  {DIM}{desc}{RESET}" if desc else f"  {DIM}—{RESET}")
+
+        lines.append(divider)
+        if self._editing:
+            lines.append(f"  {DIM}enter confirm  esc cancel{RESET}")
+        else:
+            lines.append(
+                f"  {DIM}↑/↓ move  enter/spc toggle  esc cancel  type to search{RESET}"
+            )
+
+        return lines
+
+    # ── Internal ──────────────────────────────────────────────────────────────
+
+    def _confirm_edit(self) -> None:
+        buf = self._edit_buffer.strip()
+        edit_id = self._edit_id
+        self._editing = False
+        self._edit_buffer = ""
+        self._edit_id = None
+        if edit_id and buf:
+            self._apply_value(edit_id, buf)
+
+    def _apply_value(self, item_id: str, val: str) -> None:
+        for item in self._all_items:
+            if item.id == item_id:
+                item.current_value = val
+                break
+        for item in self._filtered:
+            if item.id == item_id:
+                item.current_value = val
+                break
+        self._on_change(item_id, val)
+
+    def _refilter(self) -> None:
+        if not self._search:
+            self._filtered = list(self._all_items)
+        else:
+            q = self._search.lower()
+            self._filtered = [i for i in self._all_items if q in i.label.lower()]
+        self._selected = min(self._selected, max(0, len(self._filtered) - 1))

tau/tui/components/settings_schema.py

@@ -0,0 +1,203 @@
+"""Build a ``/settings`` sub-panel for an extension from a declarative manifest schema.
+
+Extensions can describe their settings in ``manifest.json`` instead of writing
+imperative ``register_settings`` code. The framework reads the schema, builds the
+panel, reads current values from the extension's config, and wires an ``on_change``
+that — only when a value actually changed — persists to settings.json and reloads
+just that extension so the change applies live.
+
+Manifest shape (under the app key, e.g. ``"tau"``)::
+
+    "settings": {
+      "title": "Web search",
+      "fields": [
+        {"key": "engine", "label": "Search engine", "type": "enum",
+         "values": ["ddgs", "exa", "tavily"], "default": "ddgs"},
+
+        {"key": "exa", "label": "Exa", "type": "group", "fields": [
+          {"key": "api_key", "label": "API key", "type": "secret"},
+          {"key": "results", "label": "Results", "type": "int",
+           "default": 10, "min": 1, "max": 50}
+        ]}
+      ]
+    }
+
+Field ``type`` values:
+  group           nested sub-panel; ``fields`` are rendered one level deeper and
+                  their keys are prefixed with the group key (``exa.api_key``)
+  enum / select   cycle through ``values`` (required, non-empty)
+  bool            toggle off/on (stored in config as a JSON boolean)
+  int             numeric text input; optional ``min`` / ``max`` clamp
+  string / secret free text input; optional ``pattern`` (regex) the value must match
+
+Keys support dot-notation directly too (``"exa.api_key"``). Unknown types and
+malformed fields are skipped with a logged warning rather than rendering a
+misleading control.
+"""
+from __future__ import annotations
+
+import logging
+import re
+from typing import Any, Callable
+
+from tau.extensions.api import ExtensionSettingsRegistration
+from tau.tui.components.settings_modal import SettingItem
+
+_log = logging.getLogger(__name__)
+
+_LEAF_TYPES = {"enum", "select", "bool", "int", "string", "secret", "text"}
+
+
+def _get_nested(d: dict, path: str, default: Any = "") -> Any:
+    obj: Any = d
+    for part in path.split("."):
+        if not isinstance(obj, dict) or part not in obj:
+            return default
+        obj = obj[part]
+    return obj if obj is not None else default
+
+
+def _coerce(field_type: str, value: str, field: dict) -> Any:
+    """Convert the panel's string value to the type the config should store."""
+    if field_type == "bool":
+        return str(value).lower() in ("on", "true")
+    if field_type == "int":
+        try:
+            n = int(value)
+        except (TypeError, ValueError):
+            return field.get("default", 0)
+        lo, hi = field.get("min"), field.get("max")
+        if isinstance(lo, int):
+            n = max(lo, n)
+        if isinstance(hi, int):
+            n = min(hi, n)
+        return n
+    return value
+
+
+def _valid(field_type: str, value: str, field: dict) -> bool:
+    """Reject an incoming value that violates the field's declared constraints."""
+    if field_type == "int":
+        try:
+            int(value)
+        except (TypeError, ValueError):
+            return False
+    if field_type in ("string", "secret", "text"):
+        pattern = field.get("pattern")
+        if pattern and not re.fullmatch(pattern, value or ""):
+            return False
+    return True
+
+
+def build_manifest_panel(
+    schema: dict,
+    config: dict,
+    *,
+    default_title: str,
+    apply: Callable[[str, Any], None],
+) -> ExtensionSettingsRegistration | None:
+    """Construct an :class:`ExtensionSettingsRegistration` from a manifest schema.
+
+    ``apply(key, value)`` is called with the full dot-path key and the coerced
+    value when — and only when — a field's value actually changes. Returns
+    ``None`` if the schema yields no usable items.
+    """
+    field_defs: dict[str, dict] = {}   # full key -> field def (for coerce/validate)
+    currents: dict[str, Any] = {}      # full key -> current config value (for diff)
+
+    def build_items(fields: list, prefix: str) -> list[SettingItem]:
+        items: list[SettingItem] = []
+        for f in fields:
+            if not isinstance(f, dict):
+                _log.warning("settings_schema: skipping non-object field %r", f)
+                continue
+            key = f.get("key")
+            if not key:
+                _log.warning("settings_schema: skipping field with no 'key': %r", f)
+                continue
+            full = f"{prefix}.{key}" if prefix else key
+            label = f.get("label", key)
+            description = f.get("description", "")
+            ftype = str(f.get("type") or "string").lower()
+
+            # ── Nested group → sub-panel ──────────────────────────────────────
+            if ftype == "group" or "fields" in f:
+                children = build_items(f.get("fields") or [], full)
+                if children:
+                    items.append(SettingItem(
+                        id=full, label=label, description=description,
+                        current_value="→",
+                        submenu_title=f.get("title") or label,
+                        submenu_settings=children,
+                    ))
+                continue
+
+            if ftype not in _LEAF_TYPES:
+                _log.warning("settings_schema: unknown field type %r for %r — skipping", ftype, full)
+                continue
+            if ftype in ("enum", "select") and not f.get("values"):
+                _log.warning("settings_schema: enum field %r has no values — skipping", full)
+                continue
+
+            current = _get_nested(config, full, f.get("default", ""))
+            field_defs[full] = f
+
+            if ftype in ("enum", "select"):
+                currents[full] = current
+                items.append(SettingItem(
+                    id=full, label=label, description=description,
+                    current_value=str(current),
+                    values=[str(v) for v in f.get("values", [])],
+                ))
+            elif ftype == "bool":
+                stored = current is True or str(current).lower() in ("true", "on")
+                currents[full] = stored  # config-space bool, matches _coerce output
+                items.append(SettingItem(
+                    id=full, label=label, description=description,
+                    current_value="on" if stored else "off",
+                    values=["off", "on"],
+                ))
+            else:  # string, secret, int, text
+                currents[full] = current
+                items.append(SettingItem(
+                    id=full, label=label, description=description,
+                    current_value=str(current if current is not None else ""),
+                    text_input=True,
+                ))
+        return items
+
+    items = build_items(schema.get("fields") or [], "")
+    if not items:
+        return None
+
+    # Surface the first top-level bool (e.g. a master "Enabled" switch) as an
+    # on/off summary on the extension's parent row in the main /settings list.
+    summary = ""
+    summary_key = ""
+    for f in schema.get("fields") or []:
+        if isinstance(f, dict) and str(f.get("type") or "").lower() == "bool" and f.get("key"):
+            summary_key = f["key"]
+            summary = "on" if currents.get(summary_key) else "off"
+            break
+
+    def on_change(key: str, value: str) -> None:
+        field = field_defs.get(key)
+        if field is None:
+            return  # not a leaf field we built (e.g. a group row) — ignore
+        ftype = str(field.get("type") or "string").lower()
+        if not _valid(ftype, value, field):
+            _log.warning("settings_schema: invalid value %r for %r — ignored", value, key)
+            return
+        coerced = _coerce(ftype, value, field)
+        if coerced == currents.get(key):
+            return  # no change vs in-memory config — skip persist + reload
+        currents[key] = coerced
+        apply(key, coerced)
+
+    return ExtensionSettingsRegistration(
+        title=schema.get("title") or default_title,
+        items=items,
+        on_change=on_change,
+        summary=summary,
+        summary_key=summary_key,
+    )