stcode 0.0.1a0__py3-none-any.whl

stcode/cli/ui/app.py

@@ -0,0 +1,136 @@
+"""Application lifecycle and the app-owned daemon stream."""
+
+from __future__ import annotations
+
+import contextlib
+from contextlib import aclosing
+from pathlib import Path
+from typing import Callable, ClassVar
+
+from textual import work
+from textual.app import App
+from textual.binding import Binding, BindingType
+
+from stcode.cli import labels
+from stcode.cli.logic.connection import Connection
+from stcode.cli.logic.state import ClientState
+from stcode.cli.models import StartOptions, ThemePreference, UiPrefs
+from stcode.cli.ui.screens.chat.screen import ChatScreen
+from stcode.cli.ui.screens.connect import ConnectScreen
+from stcode.cli.ui.screens.trust import TrustScreen
+from stcode.cli.ui.theme import THEMES, TerminalMode, theme_name_for
+
+
+class StcodeApp(App[None]):
+    TITLE = "stcode"
+    ENABLE_COMMAND_PALETTE = False
+    CSS_PATH = "app.tcss"
+    BINDINGS: ClassVar[list[BindingType]] = [
+        Binding("ctrl+q", "quit", "Quit", priority=True)
+    ]
+
+    def __init__(
+        self,
+        connection: Connection,
+        state: ClientState,
+        options: StartOptions,
+        prefs: UiPrefs,
+        prefs_path: Path,
+        *,
+        save_preferences: Callable[[], None],
+        restart: bool = False,
+        terminal_mode: TerminalMode = "dark",
+    ) -> None:
+        super().__init__()
+        self.connection, self.state, self.options = connection, state, options
+        self.prefs = prefs
+        self._save_preferences = save_preferences
+        self._restart = restart
+        self._terminal_mode = terminal_mode
+        self.chat = ChatScreen(
+            connection,
+            state,
+            options,
+            prefs,
+            prefs_path,
+            request_connection=self.connect,
+            choose_theme=self.set_theme,
+        )
+
+    def get_default_screen(self) -> ChatScreen:
+        return self.chat
+
+    def on_mount(self) -> None:
+        for theme in THEMES:
+            self.register_theme(theme)
+        self.theme = theme_name_for(self.prefs.theme, detected=self._terminal_mode)
+        self._start()
+
+    @work
+    async def _start(self) -> None:
+        if not self.options.daemonless and not self.prefs.is_trusted(self.options.cwd):
+            if not await self.push_screen_wait(TrustScreen(self.options.cwd)):
+                self.exit()
+                return
+            self.prefs.trust(self.options.cwd)
+            self._save_preferences()
+        self.connect()
+
+    def set_theme(self, preference: ThemePreference) -> None:
+        self.prefs.theme = preference
+        self.theme = theme_name_for(preference, detected=self._terminal_mode)
+        self._save_preferences()
+
+    async def on_unmount(self) -> None:
+        with contextlib.suppress(Exception):
+            await self.connection.aclose()
+
+    @work(exclusive=True, group="daemon")
+    async def connect(self, ask: bool = False) -> None:
+        """Keep the pump alive across modal screens; reconnect cancels its predecessor."""
+        await self.connection.close_client()
+        self.state.session_id = ""
+        try:
+            if ask or self.options.daemonless:
+                reason = labels.CONNECT_INTRO
+                while True:
+                    address = await self.push_screen_wait(
+                        ConnectScreen(self.connection.address, reason=reason)
+                    )
+                    if address is None:
+                        raise ConnectionError(labels.DAEMONLESS_CANCELLED)
+                    try:
+                        client = await self.connection.open(address=address)
+                    except OSError:
+                        reason = labels.CONNECT_RETRY
+                        continue
+                    break
+            else:
+                client = await self.connection.open(restart=self._restart)
+                self._restart = False
+        except Exception as exc:
+            self.chat.presenter.error(labels.daemon_failed(exc))
+            return
+
+        self.chat.presenter.note(
+            labels.daemon_connected(self.connection.address, self.connection.started)
+        )
+        try:
+            self.state.config = await client.get_config()
+        except Exception as exc:
+            self.chat.presenter.error(labels.daemon_failed(exc))
+        try:
+            info = await self.chat.sessions.open()
+        except Exception as exc:
+            self.chat.presenter.error(labels.daemon_failed(exc))
+            return
+        self.chat._adopt_session(info)
+        self.chat.presenter.note(labels.session_started(info.get("cwd", "")))
+        if not self.state.has_credential:
+            self.chat._open_settings(first_run=True)
+        self.chat._load_info()
+
+        # Close the iterator on cancellation while the event loop still exists.
+        async with aclosing(client.events()) as frames:
+            async for frame in frames:
+                self.chat.handle_frame(frame)

stcode/cli/ui/app.tcss

@@ -0,0 +1,3 @@
+Screen {
+    background: $background;
+}

stcode/cli/ui/components/banner.py

@@ -0,0 +1,78 @@
+"""
+Banner — the ASCII wordmark, centred on an empty transcript and gone once there is a
+conversation.
+
+It is a greeting, not furniture: the screen exists for the conversation, and a wordmark
+that stays pinned to the top of a long one is six rows of nothing. `Banner.follow()`
+takes the decision from the transcript rather than counting messages — "does it scroll
+yet" is the honest test of "is this long", at any terminal height.
+
+Lines are padded to a common width at import time rather than carrying trailing spaces
+in the source (linters strip those), because `text-align: center` centers each line
+independently and ragged lines render as a crooked wordmark.
+"""
+
+from __future__ import annotations
+
+from textual.events import Resize
+from textual.widgets import Static
+
+_FULL_LINES = [
+    "███████╗████████╗ ██████╗ ██████╗ ██████╗ ███████╗",
+    "██╔════╝╚══██╔══╝██╔════╝██╔═══██╗██╔══██╗██╔════╝",
+    "███████╗   ██║   ██║     ██║   ██║██║  ██║█████╗",
+    "╚════██║   ██║   ██║     ██║   ██║██║  ██║██╔══╝",
+    "███████║   ██║   ╚██████╗╚██████╔╝██████╔╝███████╗",
+    "╚══════╝   ╚═╝    ╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝",
+]
+
+_COMPACT_LINES = [
+    "╔═╗╔╦╗╔═╗╔═╗╔╦╗╔═╗",
+    "╚═╗ ║ ║  ║ ║ ║║║╣",
+    "╚═╝ ╩ ╚═╝╚═╝═╩╝╚═╝",
+]
+
+
+def _padded(lines: list[str]) -> str:
+    width = max(len(line) for line in lines)
+    return "\n".join(line.ljust(width) for line in lines)
+
+
+BANNER_FULL = _padded(_FULL_LINES)
+BANNER_COMPACT = _padded(_COMPACT_LINES)
+
+BANNER_FULL_WIDTH = max(len(line) for line in _FULL_LINES)
+
+
+def banner_for_width(width: int) -> str:
+    """The widest wordmark that fits, so a narrow terminal degrades instead of clipping."""
+    return BANNER_FULL if width >= BANNER_FULL_WIDTH + 4 else BANNER_COMPACT
+
+
+class Banner(Static):
+    """The wordmark, swapped for a compact one when the terminal gets narrow."""
+
+    DEFAULT_CSS = """
+    Banner {
+        height: auto;
+        padding: 1 2 1 2;
+        color: $primary;
+        text-align: center;
+    }
+    """
+
+    def __init__(self, *, id: str | None = None) -> None:  # noqa: A002 — textual's name
+        super().__init__("", id=id, markup=False)
+
+    def on_mount(self) -> None:
+        self._render_for(self.size.width)
+
+    def on_resize(self, event: Resize) -> None:
+        self._render_for(event.size.width)
+
+    def follow(self, *, transcript_scrolls: bool) -> None:
+        """Hide once there is more transcript than screen."""
+        self.display = not transcript_scrolls
+
+    def _render_for(self, width: int) -> None:
+        self.update(banner_for_width(width))

stcode/cli/ui/components/cards.py

@@ -0,0 +1,229 @@
+"""
+Cards — a list above the input, never a modal over the transcript.
+
+Everything that used to be a dialog is one of these: the help, the command list, files
+to mention, the mode and theme and effort pickers, an approval request, a question.
+
+**Why not a modal.** A modal covers the transcript, which is the thing you need in
+order to answer — *why* is it running this? A card leaves it on screen, and the turn
+keeps streaming behind it.
+
+**The input keeps focus.** A card is a list the keyboard drives from outside: the app
+forwards ↑↓ and enter to it and everything else goes into the prompt, which is what
+makes "type more to filter" work without a second text field to tab into.
+
+`token_trigger` is the other half — which of `/` and `@` is being typed right now, and
+what the filter is. `?` is not in there: it is a bare toggle on an empty input, not the
+start of a token.
+"""
+
+from __future__ import annotations
+
+from typing import Iterable, Sequence
+
+from rich.text import Text
+from textual.app import ComposeResult
+from textual.containers import Vertical
+from textual.message import Message
+from textual.widgets import OptionList, Static
+from textual.widgets.option_list import Option
+
+from stcode.cli.labels import Row
+from stcode.cli.ui.theme import brand_text
+
+VISIBLE_ROWS = 6
+"""How many rows a card shows before it scrolls. Six fits above the input on a short
+terminal and is enough to see that there is more."""
+
+LABEL_WIDTH = 13
+"""Wide enough for `shift+enter`, so the descriptions line up in one column."""
+
+
+class Card(Vertical):
+    """A titled list above the input. At most one is open at a time."""
+
+    DEFAULT_CSS = """
+    Card {
+        height: auto;
+        padding: 0 1;
+        border: none;
+        background: $surface;
+    }
+    
+    Card OptionList {
+        height: auto;
+        max-height: 6;
+        background: $surface;
+        border: none;
+        padding: 0;
+        scrollbar-size-vertical: 1;
+    }
+    
+    .card-body {
+        height: auto;
+        max-height: 11;
+        color: $text-muted;
+    }
+    """
+
+    class Chosen(Message):
+        """A row was picked. `kind` says which card, `token` carries a correlation id."""
+
+        def __init__(self, kind: str, value: str, token: str = "") -> None:
+            super().__init__()
+            self.kind = kind
+            self.value = value
+            self.token = token
+
+    def __init__(
+        self,
+        kind: str,
+        rows: Sequence[Row],
+        *,
+        title: str = "",
+        footer: str = "",
+        body: str = "",
+        token: str = "",
+        highlighted: int = 0,
+        selectable: bool = True,
+        dismissable: bool = True,
+    ) -> None:
+        super().__init__(classes="card")
+        self.kind = kind
+        self.token = token
+        """Correlation id for the request this card answers — an `execution_id` for an
+        approval or a question, empty for everything else."""
+
+        self.selectable = selectable
+        self.dismissable = dismissable
+        """Whether ++escape++ and ++backspace++ may close this card.
+
+        False for the two that are **asking** rather than offering: an approval and a
+        question. By the time one is on screen its request has already left the queue,
+        and the turn behind it is parked on an answer only this card can give — so
+        dismissing it left the session waiting on a reply with nowhere to come from, a
+        hung agent with a working keyboard. The keystroke that did it was usually
+        ++backspace++ on an already-empty input, aimed at a character that was not there.
+
+        Deny is the way out, and it costs one turn: the tool is told the user declined.
+        """
+
+        self._title = title or kind
+        self._footer = footer
+        self._body = body
+        self._rows = list(rows)
+        self._highlighted = highlighted
+        self._list = OptionList()
+
+    # ---- layout ----
+
+    def compose(self) -> ComposeResult:
+        title = Text(
+            self._title, style=f"bold {brand_text(self.app.current_theme.dark)}"
+        )
+        header = Static(title, markup=False)
+        header.add_class("card-title")
+        yield header
+        if self._body:
+            body = Static(Text(self._body), markup=False)
+            body.add_class("card-body")
+            yield body
+        yield self._list
+        if self._footer:
+            footer = Static(Text(self._footer, style="dim italic"), markup=False)
+            footer.add_class("card-footer")
+            yield footer
+
+    def on_mount(self) -> None:
+        self._fill(self._rows)
+
+    # ---- content ----
+
+    def show(self, rows: Sequence[Row]) -> None:
+        """Replace the rows — what filtering does on every keystroke."""
+        self._rows = list(rows)
+        self._fill(self._rows)
+
+    @property
+    def rows(self) -> list[Row]:
+        return list(self._rows)
+
+    def _fill(self, rows: Iterable[Row]) -> None:
+        self._list.clear_options()
+        options = [
+            Option(self._render_row(label, detail), id=label) for label, detail in rows
+        ]
+        self._list.add_options(options)
+        if options:
+            self._list.highlighted = min(self._highlighted, len(options) - 1)
+        # Height in rows, so the card is as tall as it needs to be up to the cap, and
+        # the transcript keeps everything else.
+        self._list.styles.height = min(max(len(options), 1), VISIBLE_ROWS)
+
+    @staticmethod
+    def _render_row(label: str, detail: str) -> Text:
+        text = Text()
+        text.append(label.ljust(LABEL_WIDTH) if detail else label, style="bold")
+        if detail:
+            text.append(f" {detail}", style="dim")
+        return text
+
+    # ---- driven from the prompt, which keeps focus ----
+
+    def move(self, delta: int) -> None:
+        if not self._rows:
+            return
+        current = self._list.highlighted or 0
+        self._list.highlighted = max(0, min(current + delta, len(self._rows) - 1))
+
+    def choose(self) -> bool:
+        """Pick the highlighted row. False when there is nothing to pick, which is the
+        signal to let ++enter++ mean "send" instead."""
+        if not (self.selectable and self._rows):
+            return False
+        index = self._list.highlighted or 0
+        self.post_message(self.Chosen(self.kind, self._rows[index][0], self.token))
+        return True
+
+    def choose_value(self, value: str) -> None:
+        """Pick a named row directly — what `y` and `n` do on an approval card."""
+        self.post_message(self.Chosen(self.kind, value, self.token))
+
+
+class CardZone(Vertical):
+    """The strip between the transcript and the input. Holds one card, or nothing.
+
+    **`current` is a field, not a query.** Textual removes children on the message pump,
+    so the DOM still holds the old card for a tick after `clear()` — and the caller that
+    clears one card in order to show the next runs inside that tick. Asking the DOM
+    there answers "yes, a card is open" about a card that is already on its way out, and
+    the next one never gets shown: the second of two parallel approval requests sits in
+    the queue forever while the turn waits on an answer nobody can give.
+    """
+
+    DEFAULT_CSS = """
+    CardZone { height: auto; max-height: 18; display: none; }
+    """
+
+    def __init__(self, *, id: str | None = None) -> None:  # noqa: A002 — textual's name
+        super().__init__(id=id)
+        self._current: Card | None = None
+
+    def show(self, card: Card) -> Card:
+        self.remove_children()
+        self.mount(card)
+        self._current = card
+        self.display = True
+        return card
+
+    def clear(self) -> None:
+        self.remove_children()
+        self._current = None
+        self.display = False
+
+    @property
+    def current(self) -> Card | None:
+        return self._current
+
+
+__all__ = ["LABEL_WIDTH", "VISIBLE_ROWS", "Card", "CardZone"]

stcode/cli/ui/components/prompt.py

@@ -0,0 +1,225 @@
+"""
+The prompt — a text area that keeps focus while a card is open.
+
+Two jobs beyond editing text:
+
+**Send on enter, newline on ctrl+j.** A `TextArea` does the opposite by default, and the
+default is wrong here: sending is the common act.
+
+The newline key is the part worth being careful about. ++shift+enter++ and
+++alt+enter++ only exist on the wire when the terminal speaks the **kitty keyboard
+protocol** — Textual asks for it on start-up, and a terminal that does not answer sends
+plain `CR` for shift+enter and `ESC CR` for alt+enter, both of which arrive here as a
+bare `enter`. So on those terminals the two documented newline keys *send the message*,
+which is the worst possible failure for a key whose job is to not send it.
+
+++ctrl+j++ is the one that always works: it is `LF`, a different byte from `CR`, on
+every terminal there is. It is the documented answer; the other two are kept for the
+terminals that do report them, along with the `modifyOtherKeys` spellings xterm uses.
+
+**Driving the open card without giving up focus.** ↑↓, enter, escape and — on an empty
+input — backspace are handed to the app while a card is open; everything else is
+editing, and the app re-reads the token afterwards to filter. That is what makes "type
+more to filter" work with no second field to tab into.
+
+`?` is the one character that does not insert itself: on an empty input it opens the
+help card instead. Backspace closes that card, and because nothing was inserted, typing
+`?` again inserts it — which is what you meant the second time.
+"""
+
+from __future__ import annotations
+
+from typing import ClassVar
+
+from textual.binding import Binding, BindingType
+from textual.events import Key
+from textual.message import Message
+from textual.widgets import TextArea
+
+MAX_ROWS = 8
+"""How tall the input grows before it scrolls. Past this, you are writing a document,
+and the transcript is worth more screen than the draft."""
+
+NEWLINE_KEYS = frozenset(
+    {
+        "ctrl+j",
+        "shift+enter",
+        "alt+enter",
+        # `modifyOtherKeys`, which xterm and a few others speak instead of the kitty
+        # protocol. Textual names these after the character rather than the key.
+        "shift+\r",
+        "alt+\r",
+    }
+)
+"""Every spelling of "newline, do not send". ++ctrl+j++ is the one that works
+everywhere; the rest depend on what the terminal reports. → this module's docstring."""
+
+
+class Prompt(TextArea):
+    """The input line. Grows to `MAX_ROWS`, then scrolls."""
+
+    DEFAULT_CSS = """
+    Prompt {
+        height: auto;
+        max-height: 10;
+        border: none;
+        border-left: thick $primary;
+        padding: 1 1;
+        background: $surface;
+    }
+    Prompt:focus {
+        border: none;
+        border-left: thick $primary;
+    }
+    """
+
+    BINDINGS: ClassVar[list[BindingType]] = [
+        Binding("ctrl+j", "newline", "New line", show=False),
+        Binding("alt+enter", "newline", "New line", show=False),
+    ]
+
+    class Submitted(Message):
+        def __init__(self, text: str) -> None:
+            super().__init__()
+            self.text = text
+
+    class HelpRequested(Message):
+        """`?` on an empty input."""
+
+    class CardMove(Message):
+        def __init__(self, delta: int) -> None:
+            super().__init__()
+            self.delta = delta
+
+    class CardChoose(Message):
+        """++enter++ with a card open. The app falls back to sending if nothing is
+        highlighted, so this never swallows a message."""
+
+    class CardClose(Message):
+        """++escape++, or ++backspace++ on an empty input, with a card open."""
+
+    class CardHotkey(Message):
+        """A single key the open card claimed — ++y++ and ++n++ on an approval."""
+
+        def __init__(self, value: str) -> None:
+            super().__init__()
+            self.value = value
+
+    class Interrupted(Message):
+        """++escape++ with no card open."""
+
+    class ModeCycle(Message):
+        """++shift+tab++. Handled here rather than as an app binding because a focused
+        `TextArea` claims tab and shift+tab for focus movement before one is reached,
+        and the prompt has focus the entire time the app is usable."""
+
+    def __init__(self, placeholder: str = "") -> None:
+        super().__init__(
+            id="prompt",
+            soft_wrap=True,
+            show_line_numbers=False,
+            placeholder=placeholder,
+        )
+        self.card_open = False
+        """Set by the app. The prompt does not know what a card *is* — only that its
+        arrow keys belong to something else while one is up."""
+
+        self.card_hotkeys: dict[str, str] = {}
+        """Single keys the open card has claimed, as key -> the row it picks. Empty for
+        every card but an approval: a letter that silently means something is a letter
+        you cannot type, so only a card that says so up front gets one."""
+
+    # ---- what the app needs to filter on ----
+
+    @property
+    def cursor_offset(self) -> int:
+        """The cursor as an index into `text`, which is what `token_trigger` wants."""
+        return self.document.get_index_from_location(self.cursor_location)
+
+    def clear_text(self) -> str:
+        """Empty the input and hand back what was in it."""
+        text = self.text
+        self.text = ""
+        return text
+
+    def insert_token(self, symbol: str, value: str) -> None:
+        """Replace the `symbol`-token at the cursor with `value` — how a chosen file
+        mention lands. The symbol goes too: the path is the payload."""
+        offset = self.cursor_offset
+        start = offset
+        while start > 0 and not self.text[start - 1].isspace():
+            start -= 1
+        before, after = self.text[:start], self.text[offset:]
+        self.text = f"{before}{value} {after}"
+        self.move_cursor(
+            self.document.get_location_from_index(len(before) + len(value) + 1)
+        )
+
+    # ---- keys ----
+
+    def action_newline(self) -> None:
+        self.insert("\n")
+
+    async def _on_key(self, event: Key) -> None:
+        """Intercept before `TextArea`'s own bindings see it.
+
+        `_on_key` rather than `on_key`: `TextArea` binds ++enter++ to insert a newline,
+        and a handler that runs after that binding is a handler that runs too late.
+        """
+        key = event.key
+        if self.card_open:
+            if key in ("up", "down"):
+                event.prevent_default()
+                event.stop()
+                self.post_message(self.CardMove(-1 if key == "up" else 1))
+                return
+            if key == "enter":
+                event.prevent_default()
+                event.stop()
+                self.post_message(self.CardChoose())
+                return
+            if key == "escape" or (key == "backspace" and not self.text):
+                event.prevent_default()
+                event.stop()
+                self.post_message(self.CardClose())
+                return
+            if key in self.card_hotkeys:
+                event.prevent_default()
+                event.stop()
+                self.post_message(self.CardHotkey(self.card_hotkeys[key]))
+                return
+
+        if key == "question_mark" and not self.text and not self.card_open:
+            event.prevent_default()
+            event.stop()
+            self.post_message(self.HelpRequested())
+            return
+
+        if key == "shift+tab":
+            event.prevent_default()
+            event.stop()
+            self.post_message(self.ModeCycle())
+            return
+
+        if key in NEWLINE_KEYS:
+            event.prevent_default()
+            event.stop()
+            self.insert("\n")
+            return
+
+        if key == "enter":
+            event.prevent_default()
+            event.stop()
+            self.post_message(self.Submitted(self.text))
+            return
+
+        if key == "escape":
+            event.prevent_default()
+            event.stop()
+            self.post_message(self.Interrupted())
+            return
+
+        await super()._on_key(event)
+
+
+__all__ = ["MAX_ROWS", "NEWLINE_KEYS", "Prompt"]