python-xli 0.2.0__py3-none-any.whl

xli/slash.py

@@ -0,0 +1,154 @@
+"""Slash command registry + prompt_toolkit completer.
+
+User-facing API:
+
+    @ui.command("model", description="switch model", aliases=["m"])
+    async def cmd_model(ui, args): ...
+
+Internally we keep one registry per :class:`UI` instance.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from prompt_toolkit.completion import CompleteEvent, Completer, Completion
+from prompt_toolkit.document import Document
+from prompt_toolkit.lexers import Lexer
+
+if TYPE_CHECKING:
+    from .ui import UI
+
+
+Handler = Callable[["UI", str], Awaitable[None]]
+
+
+@dataclass(frozen=True)
+class SlashCommand:
+    """One registered slash command."""
+
+    name: str
+    handler: Handler
+    description: str = ""
+    aliases: tuple[str, ...] = ()
+
+
+class SlashRegistry:
+    """Per-UI command registry. Supports aliases + prefix lookup."""
+
+    def __init__(self) -> None:
+        self._by_name: dict[str, SlashCommand] = {}
+
+    def register(self, cmd: SlashCommand) -> None:
+        self._by_name[cmd.name] = cmd
+        for alias in cmd.aliases:
+            self._by_name[alias] = cmd
+
+    def unregister(self, name: str) -> None:
+        cmd = self._by_name.pop(name, None)
+        if cmd is None:
+            return
+        for alias in cmd.aliases:
+            self._by_name.pop(alias, None)
+
+    def get(self, name: str) -> SlashCommand | None:
+        return self._by_name.get(name)
+
+    def all(self) -> list[SlashCommand]:
+        """Each canonical command once (aliases deduped)."""
+        seen: set[str] = set()
+        out: list[SlashCommand] = []
+        for cmd in self._by_name.values():
+            if cmd.name in seen:
+                continue
+            seen.add(cmd.name)
+            out.append(cmd)
+        out.sort(key=lambda c: c.name)
+        return out
+
+    def match(self, prefix: str, *, limit: int = 12) -> list[SlashCommand]:
+        prefix = prefix.lstrip("/").lower()
+        if not prefix:
+            return self.all()[:limit]
+        out: list[SlashCommand] = []
+        seen: set[str] = set()
+        # Names that start with the prefix first.
+        for cmd in self.all():
+            if cmd.name.startswith(prefix):
+                out.append(cmd)
+                seen.add(cmd.name)
+        # Then aliases that start with prefix (but commands not yet listed).
+        for name, cmd in self._by_name.items():
+            if cmd.name in seen:
+                continue
+            if name.startswith(prefix):
+                out.append(cmd)
+                seen.add(cmd.name)
+        return out[:limit]
+
+    def parse(self, line: str) -> tuple[SlashCommand | None, str]:
+        """Split ``/<name> <args>`` → (cmd-or-None, args)."""
+        if not line.startswith("/"):
+            return None, line
+        body = line[1:].lstrip()
+        name, _, args = body.partition(" ")
+        return self.get(name.lower()), args
+
+
+class SlashCompleter(Completer):
+    """prompt_toolkit completer for slash commands.
+
+    Active only when the buffer starts with ``/`` and contains no spaces yet.
+    Yields each matching command name as a completion.
+    """
+
+    def __init__(self, registry: SlashRegistry) -> None:
+        self.registry = registry
+
+    def get_completions(self, document: Document, complete_event: CompleteEvent):
+        text = document.text_before_cursor
+        if not text.startswith("/"):
+            return
+        if " " in text:
+            return
+        prefix = text[1:]
+        for cmd in self.registry.match("/" + prefix):
+            yield Completion(
+                cmd.name,
+                start_position=-len(prefix),
+                display=f"/{cmd.name}",
+                display_meta=cmd.description,
+            )
+
+
+class SlashLexer(Lexer):
+    """Highlight a *recognized* ``/command`` in the composer.
+
+    The moment the typed first word is an exact registered command (or alias), the
+    ``/name`` token is styled with ``class:slash`` — a recognition cue. While it's only
+    a partial match (``/imag``) it stays default-colored, so the color flips exactly at
+    the full-match boundary and reverts on backspace. Arguments after the command and
+    any non-command text render normally.
+    """
+
+    def __init__(self, registry: SlashRegistry, style: str = "class:slash") -> None:
+        self.registry = registry
+        self.style = style
+
+    def lex_document(self, document: Document):
+        lines = document.lines
+
+        def get_line(lineno: int):
+            text = lines[lineno] if lineno < len(lines) else ""
+            if lineno == 0 and text.startswith("/"):
+                name, sep, rest = text[1:].partition(" ")
+                if name and self.registry.get(name.lower()) is not None:
+                    frags = [(self.style, "/" + name)]
+                    if sep:
+                        frags.append(("", sep + rest))
+                    return frags
+            return [("", text)]
+
+        return get_line

xli/status.py

@@ -0,0 +1,59 @@
+"""Status bar — named fields rendered into prompt_toolkit's bottom toolbar.
+
+Usage from a UI handler::
+
+    ui.status.set(model="gpt-5-codex", tokens="3.2k/400k")
+
+Only fields listed in :class:`UI`'s ``status_fields`` are rendered; that
+keeps the bar tidy and the order stable.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from prompt_toolkit.formatted_text import FormattedText
+
+from .theme import Theme
+
+
+class StatusBar:
+    """Tracks named-field state. Used by the Composer's bottom toolbar callable."""
+
+    def __init__(
+        self,
+        *,
+        fields: Iterable[str],
+        theme: Theme,
+    ) -> None:
+        self._order = tuple(fields)
+        self._values: dict[str, str] = {f: "" for f in self._order}
+        self._theme = theme
+
+    def set(self, **kwargs: object) -> None:
+        for key, value in kwargs.items():
+            if key not in self._values:
+                # Unknown fields are silently ignored — UIs evolve; better
+                # than throwing in the middle of a turn.
+                continue
+            self._values[key] = "" if value is None else str(value)
+
+    def get(self, name: str) -> str:
+        return self._values.get(name, "")
+
+    def render(self) -> FormattedText:
+        """Render as prompt_toolkit ``FormattedText`` for the bottom toolbar."""
+        parts: list[tuple[str, str]] = []
+        first = True
+        for name in self._order:
+            value = self._values.get(name, "")
+            if not value:
+                continue
+            if not first:
+                parts.append(("class:status-sep", self._theme.status_separator))
+            parts.append(("class:status", value))
+            first = False
+        return FormattedText(parts)
+
+    def is_empty(self) -> bool:
+        return not any(self._values.values())

xli/theme.py

@@ -0,0 +1,153 @@
+"""Visual theme — colors, glyphs, role styling.
+
+Themes are dataclasses, not classes you subclass. To customize, instantiate
+:class:`Theme` with the fields you want to override; everything else uses
+the codex-inspired defaults.
+
+Three presets are bundled:
+
+* ``"codex"`` (default) — flowing log, no borders, glyph-driven gutters
+* ``"minimal"`` — even more austere: no glyphs, just indented text
+* ``"boxed"`` — for users who want Rich-style rounded panels
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+from typing import Literal
+
+ThemeName = Literal["codex", "minimal", "boxed"]
+
+
+@dataclass(frozen=True)
+class Theme:
+    """Visual configuration for the UI. All fields have sane defaults."""
+
+    # --- role labels ---
+    user_label: str = "you"
+    assistant_label: str = "assistant"
+    system_label: str = "system"
+    show_role_labels: bool = True
+
+    user_color: str = "cyan"
+    assistant_color: str = "green"
+    system_color: str = "grey50"
+
+    # --- structural glyphs ---
+    tool_glyph: str = "▸"
+    tool_done_glyph: str = "✓"
+    tool_error_glyph: str = "✗"
+    tool_cancelled_glyph: str = "⦻"
+    tool_color: str = "blue"
+    tool_output_indent: int = 2
+
+    reasoning_glyph: str = "│"
+    reasoning_color: str = "grey50"
+
+    plan_pending_glyph: str = "☐"
+    plan_in_progress_glyph: str = "▸"
+    plan_completed_glyph: str = "☑"
+    plan_color: str = "magenta"
+
+    approval_glyph: str = "⚠"
+    approval_color: str = "yellow"
+
+    error_color: str = "red"
+    warning_color: str = "yellow"
+    success_color: str = "green"
+    muted_color: str = "grey50"
+
+    # --- diff ---
+    diff_add_color: str = "green"
+    diff_del_color: str = "red"
+    diff_hunk_color: str = "magenta"
+
+    # --- code blocks (passed to rich.Syntax) ---
+    code_theme: str = "monokai"
+    code_word_wrap: bool = True
+    code_background: bool = False
+
+    # --- composer ---
+    # The prompt is a glyph in a soft accent color — NOT a filled block. We avoid
+    # solid backgrounds for chrome (see docs/theme.md): separation comes from font
+    # color + a thin rule, so the UI reads "light" and terminal-native.
+    prompt_glyph: str = ">"
+    prompt_color: str = "bold cyan"            # foreground of the glyph
+    prompt_bg: str = ""                         # no background block
+    prompt_text_color: str = "default"          # typed text uses the terminal's own fg
+    command_color: str = "bold cyan"            # a recognized /command in the composer
+    multiline_continuation: str = "  "
+
+    # --- borders / spacing ---
+    use_borders: bool = False
+    panel_border: str = "rounded"  # if use_borders is True
+    item_spacing: int = 1           # blank lines between transcript items
+
+    # --- status bar ---
+    status_separator: str = "  ·  "
+    status_color: str = "grey50"
+
+    @classmethod
+    def named(cls, name: ThemeName) -> Theme:
+        if name == "codex":
+            return CODEX
+        if name == "minimal":
+            return MINIMAL
+        if name == "boxed":
+            return BOXED
+        raise ValueError(f"unknown theme: {name!r}")
+
+    def with_overrides(self, **kwargs) -> Theme:
+        """Return a copy with the given fields replaced."""
+        return replace(self, **kwargs)
+
+
+# ---------------------------------------------------------------------------
+# Presets
+# ---------------------------------------------------------------------------
+
+
+#: The default theme. Aesthetic: codex / aider — minimal, glyph-driven, no boxes.
+CODEX = Theme()
+
+#: Even quieter — no glyphs, no colors except where strictly needed.
+MINIMAL = Theme(
+    show_role_labels=True,
+    user_color="default",
+    assistant_color="default",
+    tool_glyph=">",
+    tool_done_glyph="[ok]",
+    tool_error_glyph="[x]",
+    tool_cancelled_glyph="[-]",
+    tool_color="default",
+    reasoning_glyph=" ",
+    reasoning_color="default",
+    plan_pending_glyph="[ ]",
+    plan_in_progress_glyph="[~]",
+    plan_completed_glyph="[x]",
+    plan_color="default",
+    approval_glyph="!",
+    approval_color="default",
+    prompt_glyph=">",
+    prompt_color="default",
+    prompt_bg="",
+    prompt_text_color="default",
+    command_color="bold",  # austere: recognition via weight, not color
+)
+
+#: For users who want rounded panels around each item.
+BOXED = Theme(
+    use_borders=True,
+    show_role_labels=True,
+    tool_glyph="▸",
+    item_spacing=0,
+)
+
+
+def resolve(theme: Theme | ThemeName | None) -> Theme:
+    """Accept ``Theme`` instance, name string, or None (→ default)."""
+    if theme is None:
+        return CODEX
+    if isinstance(theme, Theme):
+        return theme
+    return Theme.named(theme)