shikiru-cli 0.2.0__py3-none-any.whl

shikiru/ui/strip.py

@@ -0,0 +1,332 @@
+"""The task strip renderable."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum, auto
+from typing import TYPE_CHECKING
+
+from rich.cells import cell_len
+from rich.text import Text
+
+from shikiru.domain.tasks import Mode, Role
+from shikiru.ui.glyphs import (
+    GLYPH_DONE,
+    GLYPH_ESCALATED,
+    GLYPH_OPERATOR,
+    GLYPH_PAUSED,
+    GLYPH_PENDING,
+    GLYPH_STALLED,
+    PANEL_KANJI,
+    ROLE_GLYPHS,
+    STAGE_IMPLEMENT,
+    STAGE_MERGE,
+    STAGE_PLAN,
+    STAGE_TRIAGE,
+    STAGE_VERIFY,
+)
+from shikiru.ui.tokens import (
+    ALERT_COLOR,
+    ENGINE_COLOR,
+    HOLD_COLOR,
+    IDLE_COLOR,
+    ROLE_COLORS,
+    STYLE_BOLD,
+    STYLE_DIM,
+    STYLE_REVERSE,
+    SUCCESS_COLOR,
+)
+
+if TYPE_CHECKING:
+    from datetime import datetime
+
+STRIP_WIDE_MIN_COLUMNS = 60
+
+
+class PanelState(StrEnum):
+    """One panel's progress."""
+
+    PENDING = auto()
+    ACTIVE = auto()
+    DONE = auto()
+    ESCALATED = auto()
+    STALLED = auto()
+
+
+class StampKind(StrEnum):
+    """A hold drawn over the active panel."""
+
+    PAUSED = auto()
+    OPERATOR = auto()
+    VERDICT = auto()
+    MERGED = auto()
+
+
+_STATE_GLYPHS: dict[PanelState, str] = {
+    PanelState.PENDING: GLYPH_PENDING,
+    PanelState.DONE: GLYPH_DONE,
+    PanelState.ESCALATED: GLYPH_ESCALATED,
+    PanelState.STALLED: GLYPH_STALLED,
+}
+_STATE_STYLES: dict[PanelState, str] = {
+    PanelState.PENDING: f"{STYLE_DIM} {IDLE_COLOR}",
+    PanelState.DONE: f"{STYLE_BOLD} {SUCCESS_COLOR}",
+    PanelState.ESCALATED: f"{STYLE_REVERSE} {ALERT_COLOR}",
+    PanelState.STALLED: f"{STYLE_BOLD} {HOLD_COLOR}",
+}
+_STAMP_GLYPHS: dict[StampKind, str] = {
+    StampKind.PAUSED: GLYPH_PAUSED,
+    StampKind.OPERATOR: GLYPH_OPERATOR,
+    StampKind.VERDICT: GLYPH_DONE,
+    StampKind.MERGED: GLYPH_DONE,
+}
+_STAMP_WORDS: dict[StampKind, str] = {
+    StampKind.PAUSED: "PAUSED",
+    StampKind.OPERATOR: "OPERATOR",
+    StampKind.VERDICT: "VERDICT",
+    StampKind.MERGED: "MERGED",
+}
+
+_NARROW_SEPARATOR = " "
+_HEADER_SEPARATOR = " · "
+
+_BORDER_TOP_LEFT = "┏"
+_BORDER_TOP_RIGHT = "┓"
+_BORDER_BOTTOM_LEFT = "┗"
+_BORDER_BOTTOM_RIGHT = "┛"
+_BORDER_BOTTOM_JOIN = "┻"
+_BORDER_HORIZONTAL = "━"
+_BORDER_VERTICAL = "┃"
+_TOP_BORDER_PREFIX = f"{_BORDER_TOP_LEFT}{_BORDER_HORIZONTAL} "
+
+_MODE_PANEL_LABELS: dict[Mode, tuple[tuple[str, str], ...]] = {
+    Mode.IMPLEMENT: (
+        ("Triage", STAGE_TRIAGE),
+        ("Implement", STAGE_IMPLEMENT),
+        ("Verify", STAGE_VERIFY),
+        ("Merge", STAGE_MERGE),
+    ),
+    Mode.PLAN: (
+        ("Triage", STAGE_TRIAGE),
+        ("Plan", STAGE_PLAN),
+        ("—", ""),
+        ("Merge", STAGE_MERGE),
+    ),
+}
+
+
+def panel_specs_for_mode(mode: Mode) -> tuple[tuple[str, str], ...]:
+    """Return this mode's `(label, stage glyph)` panels."""
+    return _MODE_PANEL_LABELS[mode]
+
+
+@dataclass(frozen=True)
+class PanelView:
+    """One panel of a task strip.
+
+    `role` is the acting role, shown as the panel colour while `state` is `ACTIVE`; other
+    states carry a fixed colour regardless of role.
+    """
+
+    label: str
+    state: PanelState
+    stage_glyph: str = ""
+    detail: str = ""
+    role_line: str = ""
+    spinner_frame: str = ""
+    role: Role | None = None
+
+
+@dataclass(frozen=True)
+class StripStamp:
+    """A hold drawn over the strip's active panel."""
+
+    kind: StampKind
+    detail: str = ""
+    flash: bool = False
+
+    def render(self) -> str:
+        """Render as `<glyph> <WORD>`, with `detail` appended when set (e.g. a reset time)."""
+        text = f"{_STAMP_GLYPHS[self.kind]} {_STAMP_WORDS[self.kind]}"
+        return f"{text} · {self.detail}" if self.detail else text
+
+
+@dataclass(frozen=True)
+class TaskStripData:
+    """Everything `TaskStrip` needs to render one task, already resolved by its caller."""
+
+    task_id: str
+    title: str
+    panels: tuple[PanelView, ...] = ()
+    stamp: StripStamp | None = None
+    actual_step_started_at: datetime | None = None
+    last_signal_at: datetime | None = None
+    last_signal: str | None = None
+    last_words: str | None = None
+
+
+def _fit(text: str, width: int) -> str:
+    if cell_len(text) <= width:
+        return text + " " * (width - cell_len(text))
+    truncated = Text(text)
+    truncated.truncate(width, overflow="crop")
+    return truncated.plain
+
+
+def _panel_style(panel: PanelView) -> str:
+    if panel.state is PanelState.ACTIVE:
+        color = ROLE_COLORS[panel.role] if panel.role is not None else ENGINE_COLOR
+        return f"{STYLE_BOLD} {color}"
+    return _STATE_STYLES[panel.state]
+
+
+def _narrow_glyph(panel: PanelView) -> str:
+    if panel.state is PanelState.ACTIVE:
+        return panel.spinner_frame or GLYPH_PENDING
+    return _STATE_GLYPHS[panel.state]
+
+
+def _header_cell(index: int, panel: PanelView) -> str:
+    pieces = (PANEL_KANJI[index], panel.stage_glyph, panel.label)
+    return " ".join(piece for piece in pieces if piece)
+
+
+def _body_cell(panel: PanelView) -> str:
+    if panel.state is PanelState.ACTIVE:
+        role_glyph = ROLE_GLYPHS[panel.role] if panel.role is not None else ""
+        pieces = (panel.spinner_frame or GLYPH_PENDING, role_glyph, panel.detail)
+    else:
+        pieces = (_STATE_GLYPHS[panel.state], panel.detail)
+    return " ".join(piece for piece in pieces if piece)
+
+
+def _stamp_index(panels: tuple[PanelView, ...]) -> int | None:
+    active = _active_index(panels)
+    if active is not None:
+        return active
+    for index in range(len(panels) - 1, -1, -1):
+        if panels[index].state is not PanelState.PENDING:
+            return index
+    return 0 if panels else None
+
+
+def _active_or_last(panels: tuple[PanelView, ...]) -> PanelView:
+    for panel in panels:
+        if panel.state is PanelState.ACTIVE:
+            return panel
+    for panel in reversed(panels):
+        if panel.state is not PanelState.PENDING:
+            return panel
+    return panels[0]
+
+
+def _active_index(panels: tuple[PanelView, ...]) -> int | None:
+    for index, panel in enumerate(panels):
+        if panel.state is PanelState.ACTIVE:
+            return index
+    return None
+
+
+def _column_widths(width: int, headers: list[str]) -> list[int]:
+    count = len(headers)
+    available = width - (count + 1)
+    minimums = [cell_len(header) for header in headers]
+    if sum(minimums) > available:
+        base = available // count
+        widths = [base] * count
+        widths[-1] += available - base * count
+        return widths
+    widths = list(minimums)
+    widths[-1] += available - sum(minimums)
+    return widths
+
+
+def _top_border(header: str, width: int) -> str:
+    fixed = cell_len(_TOP_BORDER_PREFIX) + 1 + cell_len(_BORDER_TOP_RIGHT)
+    header = _fit(header, max(width - fixed, 0)).rstrip()
+    fill = width - cell_len(_TOP_BORDER_PREFIX) - cell_len(header) - 1 - cell_len(_BORDER_TOP_RIGHT)
+    return f"{_TOP_BORDER_PREFIX}{header} {_BORDER_HORIZONTAL * max(fill, 0)}{_BORDER_TOP_RIGHT}"
+
+
+def _bottom_border(widths: list[int]) -> str:
+    segments = (_BORDER_HORIZONTAL * column for column in widths)
+    return f"{_BORDER_BOTTOM_LEFT}{_BORDER_BOTTOM_JOIN.join(segments)}{_BORDER_BOTTOM_RIGHT}"
+
+
+class TaskStrip:
+    """Renders one task's strip at a given terminal width."""
+
+    def __init__(self, data: TaskStripData) -> None:
+        """Hold `data`; nothing here mutates it."""
+        self._data = data
+
+    def render(self, width: int) -> Text:
+        """Render the full 4-panel strip at `width >= STRIP_WIDE_MIN_COLUMNS`, else one line."""
+        if width >= STRIP_WIDE_MIN_COLUMNS:
+            return self._render_wide(width)
+        return self._render_narrow(width)
+
+    def _header_text(self) -> str:
+        return f"{self._data.task_id}{_HEADER_SEPARATOR}{self._data.title}"
+
+    def _render_narrow(self, width: int) -> Text:
+        panel = _active_or_last(self._data.panels)
+        pieces = [
+            self._data.task_id,
+            panel.stage_glyph,
+            panel.label,
+            panel.detail,
+            panel.role_line,
+            _narrow_glyph(panel),
+        ]
+        line = _NARROW_SEPARATOR.join(piece for piece in pieces if piece)
+        if self._data.stamp is not None:
+            line = f"{line}{_HEADER_SEPARATOR}{self._data.stamp.render()}"
+        text = Text(line)
+        if self._data.stamp is not None and self._data.stamp.flash:
+            stamp = self._data.stamp.render()
+            start = line.rfind(stamp)
+            if start >= 0:
+                text.stylize(STYLE_REVERSE, start, start + cell_len(stamp))
+        if cell_len(line) > width:
+            text.truncate(width, overflow="crop")
+        return text
+
+    def _render_wide(self, width: int) -> Text:
+        panels = self._data.panels
+        headers = [_header_cell(index, panel) for index, panel in enumerate(panels)]
+        widths = _column_widths(width, headers)
+
+        header_cells = [
+            _fit(header, column) for header, column in zip(headers, widths, strict=True)
+        ]
+        body_cells = [
+            _fit(_body_cell(panel), column) for panel, column in zip(panels, widths, strict=True)
+        ]
+        role_cells = [
+            _fit(panel.role_line, column) for panel, column in zip(panels, widths, strict=True)
+        ]
+
+        stamp_index = _stamp_index(panels) if self._data.stamp is not None else None
+        if stamp_index is not None and self._data.stamp is not None:
+            body_cells[stamp_index] = _fit(self._data.stamp.render(), widths[stamp_index])
+            role_cells[stamp_index] = _fit("", widths[stamp_index])
+
+        body = Text(_top_border(self._header_text(), width), style=STYLE_BOLD)
+        for row in (header_cells, body_cells, role_cells):
+            body.append("\n")
+            body.append(_BORDER_VERTICAL)
+            for index, cell in enumerate(row):
+                style = _panel_style(panels[index]) if row is body_cells else None
+                if (
+                    row is body_cells
+                    and index == stamp_index
+                    and self._data.stamp is not None
+                    and self._data.stamp.flash
+                ):
+                    style = f"{style} {STYLE_REVERSE}"
+                body.append(cell, style=style)
+                body.append(_BORDER_VERTICAL)
+        body.append("\n")
+        body.append(_bottom_border(widths))
+        return body

shikiru/ui/theme.py

@@ -0,0 +1,83 @@
+"""Shared semantic colors for Textual screens and evidence views."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from textual.theme import Theme
+
+from shikiru.ui.tokens import (
+    ALERT_COLOR,
+    AMBER,
+    BACKGROUND_COLOR,
+    DETAIL_SURFACE_COLOR,
+    HOLD_COLOR,
+    NEUTRAL_BORDER_COLOR,
+    PRIMARY_TEXT_COLOR,
+    RAISED_SURFACE_COLOR,
+    SCROLLBAR_THUMB_ACTIVE_COLOR,
+    SCROLLBAR_THUMB_COLOR,
+    SCROLLBAR_THUMB_HOVER_COLOR,
+    SCROLLBAR_TRACK_COLOR,
+    SECONDARY_TEXT_COLOR,
+    SELECTED_SURFACE_COLOR,
+    STEEL_BLUE,
+    SUCCESS_COLOR,
+    SURFACE_COLOR,
+)
+
+if TYPE_CHECKING:
+    from textual.app import App
+
+BACKGROUND = BACKGROUND_COLOR
+SURFACE = SURFACE_COLOR
+RAISED_SURFACE = RAISED_SURFACE_COLOR
+NEUTRAL_BORDER = NEUTRAL_BORDER_COLOR
+PRIMARY_TEXT = PRIMARY_TEXT_COLOR
+SECONDARY_TEXT = SECONDARY_TEXT_COLOR
+FOCUS = STEEL_BLUE
+THEME_NAME = "shikiru"
+SCROLLBAR_WIDTH = 1
+
+SHIKIRU_THEME = Theme(
+    name=THEME_NAME,
+    primary=FOCUS,
+    secondary=SECONDARY_TEXT,
+    warning=HOLD_COLOR,
+    error=ALERT_COLOR,
+    success=SUCCESS_COLOR,
+    accent=FOCUS,
+    foreground=PRIMARY_TEXT,
+    background=BACKGROUND,
+    surface=SURFACE,
+    panel=RAISED_SURFACE,
+    variables={
+        "border": NEUTRAL_BORDER,
+        "accent": FOCUS,
+        "amber": AMBER,
+        "detail-surface": DETAIL_SURFACE_COLOR,
+        "dusty-rose": ALERT_COLOR,
+        "neutral-border": NEUTRAL_BORDER,
+        "focus": FOCUS,
+        "muted-text": SECONDARY_TEXT,
+        "primary-text": PRIMARY_TEXT,
+        "sage": SUCCESS_COLOR,
+        "scrollbar": SCROLLBAR_THUMB_COLOR,
+        "scrollbar-active": SCROLLBAR_THUMB_ACTIVE_COLOR,
+        "scrollbar-background": SCROLLBAR_TRACK_COLOR,
+        "scrollbar-background-active": SCROLLBAR_TRACK_COLOR,
+        "scrollbar-background-hover": SCROLLBAR_TRACK_COLOR,
+        "scrollbar-corner-color": SCROLLBAR_TRACK_COLOR,
+        "scrollbar-hover": SCROLLBAR_THUMB_HOVER_COLOR,
+        "scrollbar-width": str(SCROLLBAR_WIDTH),
+        "secondary-text": SECONDARY_TEXT,
+        "selected-surface": SELECTED_SURFACE_COLOR,
+        "steel-blue": STEEL_BLUE,
+    },
+)
+
+
+def install_theme[ReturnT](app: App[ReturnT]) -> None:
+    """Register the shared Shikiru palette on a Textual application."""
+    app.register_theme(SHIKIRU_THEME)
+    app.theme = THEME_NAME

shikiru/ui/tokens.py

@@ -0,0 +1,51 @@
+"""Colour tokens for the shared visual language."""
+
+from __future__ import annotations
+
+from shikiru import palette
+from shikiru.domain.levels import UsageLevel
+from shikiru.domain.tasks import Role
+
+BACKGROUND_COLOR = palette.BACKGROUND_COLOR
+SURFACE_COLOR = palette.SURFACE_COLOR
+RAISED_SURFACE_COLOR = palette.RAISED_SURFACE_COLOR
+SELECTED_SURFACE_COLOR = palette.SELECTED_SURFACE_COLOR
+DETAIL_SURFACE_COLOR = palette.DETAIL_SURFACE_COLOR
+NEUTRAL_BORDER_COLOR = palette.NEUTRAL_BORDER_COLOR
+PRIMARY_TEXT_COLOR = palette.PRIMARY_TEXT_COLOR
+SECONDARY_TEXT_COLOR = palette.SECONDARY_TEXT_COLOR
+STEEL_BLUE = palette.STEEL_BLUE
+SAGE = palette.SAGE
+AMBER = palette.AMBER
+DUSTY_ROSE = palette.DUSTY_ROSE
+SCROLLBAR_THUMB_COLOR = palette.SCROLLBAR_THUMB_COLOR
+SCROLLBAR_THUMB_HOVER_COLOR = palette.SCROLLBAR_THUMB_HOVER_COLOR
+SCROLLBAR_THUMB_ACTIVE_COLOR = palette.SCROLLBAR_THUMB_ACTIVE_COLOR
+SCROLLBAR_TRACK_COLOR = palette.SCROLLBAR_TRACK_COLOR
+
+ROLE_COLORS: dict[Role, str] = {
+    Role.LEADER: STEEL_BLUE,
+    Role.IMPLEMENTER: STEEL_BLUE,
+    Role.HELPER: STEEL_BLUE,
+}
+
+OPERATOR_COLOR = palette.STEEL_BLUE
+ENGINE_COLOR = palette.SECONDARY_TEXT_COLOR
+SUCCESS_COLOR = palette.SAGE
+REWORK_COLOR = palette.AMBER
+HOLD_COLOR = palette.AMBER
+ALERT_COLOR = palette.DUSTY_ROSE
+STOPPED_DURING = "stopped during"
+IDLE_COLOR = palette.SECONDARY_TEXT_COLOR
+
+STYLE_DIM = "dim"
+STYLE_BOLD = "bold"
+STYLE_REVERSE = "reverse"
+"""Attributes paired with every panel colour: under `NO_COLOR`, Rich keeps the
+attribute and drops the colour, giving the required monochrome bold/dim/reverse."""
+
+USAGE_LEVEL_COLORS: dict[UsageLevel, str] = {
+    UsageLevel.OK: SAGE,
+    UsageLevel.WARN: AMBER,
+    UsageLevel.ALERT: DUSTY_ROSE,
+}

shikiru/view_log.py

@@ -0,0 +1,126 @@
+"""The role view log: its path, row keys and the pane command tailing it."""
+
+from __future__ import annotations
+
+import json
+import os
+from datetime import datetime
+from typing import TYPE_CHECKING
+
+from shikiru.agents.contracts import (
+    Message,
+    SessionStarted,
+    ToolFinished,
+    ToolStarted,
+    TurnEnded,
+    TurnFailed,
+    role_dir,
+    shikiru_argv,
+)
+from shikiru.domain.quota_waits import QuotaAction
+from shikiru.private import TEXT_ENCODING, make_private_dir, write_private_text
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+VIEW_LOG_NAME = "view.jsonl"
+VIEW_TIME_KEY = "ts"
+VIEW_TURN_KEY = "turn"
+VIEW_RUNG_KEY = "rung"
+VIEW_SIGNAL_KEY = "signal"
+VIEW_MESSAGE_SIGNAL = Message.__name__
+VIEW_MESSAGE_TEXT_KEY = "text"
+VIEW_TURN_ENDED_TEXT_KEY = "last_message"
+VIEW_SESSION_STARTED_SIGNAL = SessionStarted.__name__
+VIEW_TOOL_STARTED_SIGNAL = ToolStarted.__name__
+VIEW_TOOL_FINISHED_SIGNAL = ToolFinished.__name__
+VIEW_TURN_ENDED_SIGNAL = TurnEnded.__name__
+VIEW_TURN_FAILED_SIGNAL = TurnFailed.__name__
+QUOTA_STATUS_NAME = "quota-status.json"
+QUOTA_STATUS_ACTION_KEY = "action"
+QUOTA_STATUS_AT_KEY = "at"
+TURN_DIR_SEPARATOR = "-"
+TURN_DIR_ITERATION_MARKER = "-i"
+CLI_VIEW_COMMAND = "view"
+CLI_PROJECT_FLAG = "--project"
+PARTIAL_SUFFIX = ".partial"
+_TAIL_BLOCK_BYTES = 65536
+_LINE_BREAK = b"\n"
+
+
+def ordered_turn_dirs(turns_root: Path) -> list[Path]:
+    """Return the turn directories of `turns_root` ordered by turn number, however many digits."""
+    return sorted(
+        (entry for entry in turns_root.iterdir() if entry.is_dir()),
+        key=lambda entry: int(entry.name.partition(TURN_DIR_SEPARATOR)[0]),
+    )
+
+
+def turn_iteration(turn_name: str) -> int | None:
+    """Return the task iteration a turn directory name (`NN-<step>-i<n>`) was started in."""
+    _, marker, iteration = turn_name.rpartition(TURN_DIR_ITERATION_MARKER)
+    return int(iteration) if marker and iteration.isdecimal() else None
+
+
+def view_argv(project_root: Path, task_id: str, role: str) -> tuple[str, ...]:
+    """Return the argv of `role`'s read-only view pane for `task_id`."""
+    return shikiru_argv(CLI_PROJECT_FLAG, str(project_root), CLI_VIEW_COMMAND, task_id, role)
+
+
+def view_log_path(run_dir: Path, role: str) -> Path:
+    """Return `role`'s live view log, one JSON row per agent signal."""
+    return role_dir(run_dir, role) / VIEW_LOG_NAME
+
+
+def quota_status_path(run_dir: Path, role: str) -> Path:
+    """Return the file holding `role`'s current quota status, present only during a quota wait."""
+    return role_dir(run_dir, role) / QUOTA_STATUS_NAME
+
+
+def write_quota_status(path: Path, action: QuotaAction | None, at: datetime | None) -> None:
+    """Publish a quota wait for `path`'s view pane, replacing any earlier one in a single step."""
+    payload = {
+        QUOTA_STATUS_ACTION_KEY: action.value if action is not None else None,
+        QUOTA_STATUS_AT_KEY: at.isoformat() if at is not None else None,
+    }
+    make_private_dir(path.parent)
+    partial = path.with_name(f"{path.name}{PARTIAL_SUFFIX}")
+    write_private_text(partial, json.dumps(payload))
+    partial.replace(path)
+
+
+def clear_quota_status(path: Path) -> None:
+    """Remove the quota status of `path`'s view pane; nothing happens when none is published."""
+    path.unlink(missing_ok=True)
+
+
+def read_quota_status(path: Path) -> tuple[QuotaAction | None, datetime | None] | None:
+    """Return the published quota status as its action and time, or none outside a quota wait."""
+    try:
+        text = path.read_text(encoding=TEXT_ENCODING)
+    except FileNotFoundError:
+        return None
+    payload = json.loads(text)
+    action = payload[QUOTA_STATUS_ACTION_KEY]
+    at = payload[QUOTA_STATUS_AT_KEY]
+    return (
+        QuotaAction(action) if action is not None else None,
+        datetime.fromisoformat(at) if at is not None else None,
+    )
+
+
+def read_tail_lines(path: Path, count: int) -> list[str]:
+    """Return the last `count` lines of `path`, reading no more of the file than they need."""
+    blocks: list[bytes] = []
+    line_breaks = 0
+    with path.open("rb") as handle:
+        position = handle.seek(0, os.SEEK_END)
+        while position > 0 and line_breaks <= count:
+            size = min(_TAIL_BLOCK_BYTES, position)
+            position -= size
+            handle.seek(position)
+            block = handle.read(size)
+            blocks.append(block)
+            line_breaks += block.count(_LINE_BREAK)
+    text = b"".join(reversed(blocks)).decode(TEXT_ENCODING, errors="replace")
+    return text.splitlines()[-count:]

shikiru/workspace/__init__.py

@@ -0,0 +1,3 @@
+"""Task roots, worktrees, caches and git facts."""
+
+from __future__ import annotations