shikiru-cli 0.2.0__py3-none-any.whl

shikiru/ui/console.py

@@ -0,0 +1,49 @@
+"""Human terminal output shared by CLI surfaces."""
+
+from __future__ import annotations
+
+import os
+
+from rich.console import Console
+
+OSC8_TERMINAL_PROGRAMS = frozenset(
+    {
+        "Hyper",
+        "WezTerm",
+        "contour",
+        "ghostty",
+        "vscode",
+        "iTerm.app",
+    }
+)
+OSC8_TERMINAL_NAMES = frozenset(
+    {
+        "alacritty",
+        "contour",
+        "foot",
+        "kitty",
+        "wezterm",
+        "xterm-ghostty",
+        "xterm-kitty",
+    }
+)
+MIN_VTE_OSC8_VERSION = 5000
+
+
+def human_console(*, stderr: bool = False) -> Console:
+    """Return a Rich console that keeps human data literal and detects terminal output modes."""
+    return Console(stderr=stderr, soft_wrap=True, markup=False, highlight=False, emoji=False)
+
+
+def supports_osc8(console: Console) -> bool:
+    """Return whether the active terminal is known to support OSC 8 hyperlinks."""
+    if not console.is_terminal or console.is_dumb_terminal:
+        return False
+    if os.environ.get("WT_SESSION"):
+        return True
+    if os.environ.get("TERM_PROGRAM") in OSC8_TERMINAL_PROGRAMS:
+        return True
+    if os.environ.get("TERM") in OSC8_TERMINAL_NAMES:
+        return True
+    vte_version = os.environ.get("VTE_VERSION", "")
+    return vte_version.isdecimal() and int(vte_version) >= MIN_VTE_OSC8_VERSION

shikiru/ui/fold.py

@@ -0,0 +1,50 @@
+"""The focusable one-line fold heading shared by the popups that expand a section in place."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, ClassVar
+
+from textual.binding import Binding
+from textual.message import Message
+from textual.widgets import Static
+
+from shikiru.ui.section import key_label
+
+if TYPE_CHECKING:
+    from rich.text import Text
+    from textual import events
+    from textual.binding import BindingType
+
+COLLAPSED_ARROW = "\N{BLACK RIGHT-POINTING SMALL TRIANGLE}"
+EXPANDED_ARROW = "\N{BLACK DOWN-POINTING SMALL TRIANGLE}"
+FOLD_TOGGLE_KEY = "t"
+FOLD_TOGGLE_LABEL = "show/hide"
+
+
+def fold_arrow(*, expanded: bool) -> str:
+    """Return the arrow that shows whether a fold is open."""
+    return EXPANDED_ARROW if expanded else COLLAPSED_ARROW
+
+
+def fold_toggle_hint() -> Text:
+    """Return the `t show/hide` hint shown at the right of a fold heading."""
+    return key_label(FOLD_TOGGLE_KEY, FOLD_TOGGLE_LABEL)
+
+
+class FoldLine(Static, can_focus=True):
+    """A fold heading that asks to toggle on Enter, Space or a click."""
+
+    BINDINGS: ClassVar[list[BindingType]] = [
+        Binding("enter,space", "toggle_fold", "Toggle", show=False),
+    ]
+
+    class Toggled(Message):
+        """The heading asked to expand or collapse its section."""
+
+    def action_toggle_fold(self) -> None:
+        """Ask to expand or collapse the section."""
+        self.post_message(self.Toggled())
+
+    def on_click(self, event: events.Click) -> None:
+        event.stop()
+        self.post_message(self.Toggled())

shikiru/ui/gated_static.py

@@ -0,0 +1,117 @@
+"""A `Static` that repaints only on changed output and reflows only when its size can change."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from rich.console import Group
+from rich.rule import Rule
+from rich.text import Text
+from textual.visual import Visual, visualize
+from textual.widgets import Static
+
+if TYPE_CHECKING:
+    from textual.strip import Strip
+    from textual.visual import VisualType
+
+
+@dataclass(frozen=True, slots=True)
+class _Shown:
+    width: int
+    strips: tuple[Strip, ...]
+
+    def has_same_shape(self, other: _Shown) -> bool:
+        return self.width == other.width and self._extent() == other._extent()
+
+    def _extent(self) -> tuple[int, int]:
+        return len(self.strips), max((strip.cell_length for strip in self.strips), default=0)
+
+
+@dataclass(frozen=True, slots=True)
+class _Signature:
+    width: int
+    selection: object
+    key: object
+
+
+def _renderable_key(content: object) -> object | None:
+    if isinstance(content, str):
+        return content
+    if type(content) is Group:
+        keys = tuple(_renderable_key(item) for item in content.renderables)
+        return None if None in keys else (content.fit, keys)
+    if type(content) is Rule:
+        return (content.title, content.characters, content.style, content.end, content.align)
+    if type(content) is Text:
+        return (
+            content.plain,
+            tuple(content.spans),
+            content.style,
+            content.justify,
+            content.overflow,
+            content.no_wrap,
+            content.end,
+            content.tab_size,
+        )
+    return None
+
+
+class GatedStatic(Static):
+    """Skips updates that show the same output; repaints without reflow when the extent holds."""
+
+    def __init__(
+        self,
+        content: VisualType = "",
+        *,
+        id: str | None = None,  # noqa: A002
+        classes: str | None = None,
+        markup: bool = True,
+    ) -> None:
+        super().__init__(content, id=id, classes=classes, markup=markup)
+        self._shown: _Shown | None = None
+        self._signature: _Signature | None = None
+
+    def update(self, content: VisualType = "", *, layout: bool = True) -> None:
+        """Update unconditionally and forget what was last shown."""
+        self._shown = None
+        self._signature = None
+        super().update(content, layout=layout)
+
+    def notify_style_update(self) -> None:
+        """Forget the shown signature because the styles that shape the output changed."""
+        self._signature = None
+        super().notify_style_update()
+
+    def update_if_changed(self, content: VisualType, *, key: object | None = None) -> bool:
+        """Show `content` unless it renders identically to what is shown; True when updated.
+
+        `key`, when given, asserts that `content` renders as a pure function of it and of the
+        widget's width, so an equal key skips rendering altogether.
+        """
+        width = self.content_size.width
+        has_content_sized_width = self.styles.width is not None and self.styles.width.is_auto
+        if width <= 0 or has_content_sized_width:
+            self.update(content)
+            return True
+        render_key = key if key is not None else _renderable_key(content)
+        signature = (
+            None
+            if render_key is None
+            else _Signature(width, self.text_selection, (self._render_markup, render_key))
+        )
+        if signature is not None and signature == self._signature:
+            return False
+        visual = visualize(self, content, markup=self._render_markup)
+        shown = _Shown(
+            width,
+            tuple(Visual.to_strips(self, visual, width, None, self.visual_style)),
+        )
+        previous = self._shown
+        if previous == shown:
+            self._signature = signature
+            return False
+        super().update(content, layout=previous is None or not previous.has_same_shape(shown))
+        self._shown = shown
+        self._signature = signature
+        return True

shikiru/ui/gauge.py

@@ -0,0 +1,40 @@
+"""Small coloured percentage gauges."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from rich.text import Text
+
+from shikiru.domain.levels import usage_level
+from shikiru.ui.glyphs import GAUGE_GLYPHS
+from shikiru.ui.tokens import USAGE_LEVEL_COLORS
+
+GAUGE_LEVELS = len(GAUGE_GLYPHS) - 1
+GAUGE_MAX_PCT = 100
+PERCENT_FORMAT = ".0f"
+
+
+@dataclass(frozen=True)
+class Gauge:
+    """Render a label and a glyph and percentage coloured by the usage level they reach."""
+
+    label: str
+    used_pct: float
+    warn_pct: int
+    alert_pct: int
+
+    def render(self) -> Text:
+        """Render the nearest gauge glyph and the unbounded reported percentage."""
+        level = round(min(max(self.used_pct, 0.0), GAUGE_MAX_PCT) * GAUGE_LEVELS / GAUGE_MAX_PCT)
+        glyph = GAUGE_GLYPHS[level]
+        color = USAGE_LEVEL_COLORS[
+            usage_level(self.used_pct, warn_pct=self.warn_pct, alert_pct=self.alert_pct)
+        ]
+        text = Text()
+        if self.label:
+            text.append(self.label, style="dim")
+            text.append(" ")
+        text.append(glyph, style=color)
+        text.append(f" {self.used_pct:{PERCENT_FORMAT}}%", style=color)
+        return text

shikiru/ui/glyphs.py

@@ -0,0 +1,109 @@
+"""The one glyph set shared by the CLI and the dashboard.
+
+Ambiguous-width characters (`◆ ▲ ≡ · ○ ◑ ●`) are drawn one cell wide, as Textual assumes;
+terminals set to CJK ambiguous-wide are unsupported. A character with an emoji variant
+(`⚖ ⚙ ⏸ ⚠`) carries U+FE0E, the text-presentation variation selector, because some terminals
+render it as wide color emoji without it. `is_single_cell` is the check a unit test runs over
+every glyph registered here.
+"""
+
+from __future__ import annotations
+
+import unicodedata
+
+from shikiru.domain.tasks import Role
+
+_TEXT_PRESENTATION_SELECTOR = "︎"
+_ZERO_WIDTH_CATEGORIES = frozenset({"Mn", "Me", "Cf"})
+_WIDE_EAST_ASIAN_WIDTHS = frozenset({"W", "F"})
+
+_EMOJI_CAPABLE_CODE_POINTS = frozenset({"⚖", "⚙", "⏸", "⚠"})
+"""The base characters we use that have an emoji-presentation variant (Unicode has no stdlib
+property for this, so this is the small explicit set our own glyphs draw from)."""
+
+
+def is_single_cell(glyph: str) -> bool:
+    """Return whether `glyph` renders as exactly one terminal cell in every terminal."""
+    cells = 0
+    characters = list(glyph)
+    for index, character in enumerate(characters):
+        if character == _TEXT_PRESENTATION_SELECTOR:
+            continue
+        if unicodedata.category(character) in _ZERO_WIDTH_CATEGORIES:
+            continue
+        if unicodedata.east_asian_width(character) in _WIDE_EAST_ASIAN_WIDTHS:
+            return False
+        followed_by_selector = (
+            index + 1 < len(characters) and characters[index + 1] == _TEXT_PRESENTATION_SELECTOR
+        )
+        if character in _EMOJI_CAPABLE_CODE_POINTS and not followed_by_selector:
+            return False
+        cells += 1
+    return cells == 1
+
+
+PANEL_KANJI = ("起", "承", "転", "結")
+"""Decorative kanji for the strip's four panel positions: ki-shō-ten-ketsu. Kanji
+are decorative marks, not state glyphs, so they are wide and excluded from `ALL_GLYPHS`."""
+
+STAGE_TRIAGE = "⌕"
+STAGE_PLAN = "≡"
+STAGE_IMPLEMENT = "⚒"
+STAGE_VERIFY = "⚖︎"
+STAGE_MERGE = "⑂"
+STAGE_PR = "⇪"
+
+ROLE_GLYPHS: dict[Role, str] = {
+    Role.LEADER: "◆",
+    Role.IMPLEMENTER: "▲",
+    Role.HELPER: "✦",
+}
+GLYPH_OPERATOR = "⌨"
+GLYPH_ENGINE = "⚙︎"
+
+GLYPH_DONE = "✔"
+GLYPH_REWORK = "↺"
+GLYPH_CONSULT = "?"
+GLYPH_PAUSED = "⏸︎"
+GLYPH_QUOTA = "⧗"
+QUOTA_LABEL = "quota"
+QUOTA_MARKER = f"{GLYPH_QUOTA} {QUOTA_LABEL}"
+GLYPH_STALLED = "⚠︎"
+GLYPH_WARNING = "⚠︎"
+GLYPH_ESCALATED = "‼"
+GLYPH_BLOCKED = "⊘"
+GLYPH_SLOT = "◷"
+GLYPH_PENDING = "·"
+GLYPH_STOPPED = "✕"
+GLYPH_CURRENT_STAGE = "\u203a"
+
+GAUGE_GLYPHS = ("○", "◔", "◑", "◕", "●")
+
+SPINNER_FRAMES = ("⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏")
+
+ALL_GLYPHS = (
+    STAGE_TRIAGE,
+    STAGE_PLAN,
+    STAGE_IMPLEMENT,
+    STAGE_VERIFY,
+    STAGE_MERGE,
+    STAGE_PR,
+    *ROLE_GLYPHS.values(),
+    GLYPH_OPERATOR,
+    GLYPH_ENGINE,
+    GLYPH_DONE,
+    GLYPH_REWORK,
+    GLYPH_CONSULT,
+    GLYPH_PAUSED,
+    GLYPH_QUOTA,
+    GLYPH_STALLED,
+    GLYPH_WARNING,
+    GLYPH_ESCALATED,
+    GLYPH_BLOCKED,
+    GLYPH_SLOT,
+    GLYPH_PENDING,
+    GLYPH_STOPPED,
+    GLYPH_CURRENT_STAGE,
+    *GAUGE_GLYPHS,
+    *SPINNER_FRAMES,
+)

shikiru/ui/keys.py

@@ -0,0 +1,57 @@
+"""Key names painted in the shared cyan inside hint text."""
+
+from __future__ import annotations
+
+import re
+
+from rich.text import Text
+
+from shikiru.ui.section import BOLD_STEEL
+from shikiru.ui.tokens import SECONDARY_TEXT_COLOR, STYLE_BOLD
+
+KEY_NAMES: tuple[str, ...] = (
+    "Ctrl+P",
+    "Ctrl+S",
+    "Escape",
+    "Esc",
+    "Enter",
+    "Tab",
+    "PgUp/PgDn",
+    "PgUp",
+    "PgDn",
+    "End",
+    "Up/Down",
+    "Left/Right",
+)
+KEY_SYMBOLS: tuple[str, ...] = ("↑↓", "↑", "↓", "←", "→")
+KEY_LABELLED_CHARACTERS = "a-z?/"
+BOLD_DISABLED_KEY = f"{STYLE_BOLD} {SECONDARY_TEXT_COLOR}"
+
+_KEY_PATTERN = re.compile(
+    "|".join(
+        (
+            rf"(?<!\w)(?:{'|'.join(re.escape(name) for name in KEY_NAMES)})(?!\w)",
+            "|".join(re.escape(symbol) for symbol in KEY_SYMBOLS),
+            rf"(?<!\w)[{KEY_LABELLED_CHARACTERS}](?=:)",
+        )
+    )
+)
+
+
+def key_hint(text: str, base_style: str = "", *, enabled: bool = True) -> Text:
+    """Return `text` in `base_style` with every known key name in the cyan key style.
+
+    A disabled hint (its key does nothing now) paints the keys bold grey instead.
+    """
+    key_style = BOLD_STEEL if enabled else BOLD_DISABLED_KEY
+    hint = Text(text)
+    if base_style:
+        hint.stylize(base_style)
+    for match in _KEY_PATTERN.finditer(text):
+        hint.stylize(key_style, match.start(), match.end())
+    return hint
+
+
+def append_key_hint(target: Text, text: str, base_style: str = "") -> None:
+    """Append `text` to `target` as `key_hint` does."""
+    target.append_text(key_hint(text, base_style))

shikiru/ui/live_interval.py

@@ -0,0 +1,42 @@
+"""A repeating widget timer that restarts when its configured period changes."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+
+    from textual.timer import Timer
+    from textual.widget import Widget
+
+
+class LiveInterval:
+    """Run `tick` every `period()` seconds, restarting the timer only when that period changes."""
+
+    def __init__(
+        self,
+        widget: Widget,
+        period: Callable[[], float],
+        tick: Callable[[], Awaitable[None]],
+    ) -> None:
+        """Hold the timer target; nothing runs until `apply`."""
+        self._widget = widget
+        self._period = period
+        self._tick = tick
+        self._applied: float | None = None
+        self._timer: Timer | None = None
+
+    def apply(self) -> None:
+        """Tick at the current period, replacing the running timer when the period differs."""
+        period = self._period()
+        if period == self._applied:
+            return
+        if self._timer is not None:
+            self._timer.stop()
+        self._applied = period
+        self._timer = self._widget.set_interval(period, self._tick)
+
+    async def reapply(self) -> None:
+        """Apply the current period again; a state change calls this to pick up new settings."""
+        self.apply()