comodor 0.2.1__tar.gz → 0.2.2__tar.gz

{comodor-0.2.1 → comodor-0.2.2}/.gitignore

@@ -34,3 +34,7 @@ TODO
 
 # Written by the build from the git tag.
 src/comodor/_version.py
+
+# uv writes this when it resolves an environment here. Comodor is a library
+# as well as an application; a lock file would pin its users, not just us.
+uv.lock

{comodor-0.2.1 → comodor-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: comodor
-Version: 0.2.1
+Version: 0.2.2
 Summary: Comodor — a self-improving terminal coding agent with a Rich TUI
 Project-URL: Homepage, https://comodor.ai
 Project-URL: Repository, https://github.com/ifekri/Comodor

{comodor-0.2.1 → comodor-0.2.2}/src/comodor/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.2.1'
-__version_tuple__ = version_tuple = (0, 2, 1)
+__version__ = version = '0.2.2'
+__version_tuple__ = version_tuple = (0, 2, 2)
 
 __commit_id__ = commit_id = None

{comodor-0.2.1 → comodor-0.2.2}/src/comodor/setup.py

@@ -5,10 +5,19 @@ does not ask anybody to find a dotfile, learn an environment variable or read
 documentation before their first task — it asks what it needs, in the terminal,
 with the answers numbered, and writes them down.
 
-Everything here is deliberately plain input: numbered choices and one masked
-field. The full interface needs raw terminal mode and a running event loop, and
-neither is available yet at the point setup runs — nor should the first thing a
-new user meets be a mode their terminal might not support.
+Two ways of asking, and the second one is not optional.
+
+On a real terminal each question arrives on a screen of its own: what has
+already been answered is summarised in two or three quiet lines at the top, and
+below it one framed list you move through with the arrow keys. Questions no
+longer pile up — by the fourth one the terminal used to be a transcript of
+decisions already made — and a provider with sixty models is a list you can
+filter by typing rather than sixty numbered rows to read.
+
+Anywhere without a terminal — a pipe, a test, an editor's console — the
+numbered prompt is exactly what it was. A setup wizard that only works in one
+kind of terminal is a setup wizard that cannot be scripted, and the first thing
+a new user meets must not be a mode their terminal might not support.
 """
 
 from __future__ import annotations
@@ -24,6 +33,7 @@ from rich.text import Text
 
 from . import catalogue
 from .config import Config
+from .ui import chooser
 from .ui import console as console_module
 from .ui.theme import Theme
 
@@ -57,10 +67,26 @@ class SetupWizard:
         self.console = console or console_module.build(self.theme)
         self._prompt = prompt or (lambda message: input(message))
         self._secret = secret or (lambda message: getpass.getpass(message))
+        # An injected prompt means somebody is driving this without a keyboard,
+        # so the interactive list is off whatever the terminal says it can do.
+        self._keys = prompt is None and chooser.interactive(self.console)
+        #: What has been answered so far, shown at the top of each screen.
+        self._done: list[tuple[str, str]] = []
 
     # -- presentation ----------------------------------------------------- #
 
     def _rule(self, title: str, step: int, total: int) -> None:
+        """Start a question.
+
+        On a real terminal this is where the screen is cleared. The alternative
+        — letting the questions stack — meant that by the last one the useful
+        part of the screen was a few lines at the bottom under a wall of
+        choices already made. What replaces the wall is the same information in
+        one line each, which is all it was ever worth.
+        """
+        if self._keys:
+            self.console.clear()
+            self._recap()
         self.console.print()
         self.console.print(
             Text.assemble(
@@ -69,13 +95,50 @@ class SetupWizard:
             )
         )
 
-    def _choose(self, options: Sequence[tuple[str, str, str]], default: int = 1) -> str:
-        """Print a numbered list and return the chosen value.
+    def _recap(self) -> None:
+        """The questions already answered, one quiet line each."""
+        if not self._done:
+            self.console.print(
+                Text("  Comodor setup", style=self.theme.style("dim")))
+            return
+        for label, value in self._done:
+            self.console.print(Text.assemble(
+                ("  ✓ ", self.theme.style("good")),
+                (f"{label}  ", self.theme.style("dim")),
+                (value, self.theme.style("value")),
+            ))
 
-        ``options`` is ``(value, label, note)``. Re-asks on a bad answer rather
-        than falling through to a default the user did not pick — a silent
-        wrong choice here is one they would have to undo later.
+    def _answered(self, label: str, value: str) -> None:
+        self._done.append((label, value))
+        if not self._keys:
+            return
+        # Echoed once here, because the list it came from is erased on the way
+        # out: a choice that leaves no trace reads as a choice that did not
+        # register.
+        self.console.print(Text.assemble(
+            ("  ✓ ", self.theme.style("good")),
+            (value, self.theme.style("value", bold=True)),
+        ))
+
+    def _choose(self, options: Sequence[tuple[str, str, str]], default: int = 1,
+                title: str = "") -> str:
+        """Return the chosen value, by arrow key or by number.
+
+        ``options`` is ``(value, label, note)``. The numbered path re-asks on a
+        bad answer rather than falling through to a default the user did not
+        pick — a silent wrong choice here is one they would have to undo later.
         """
+        if self._keys:
+            picked = chooser.choose(
+                self.console, self.theme,
+                [chooser.Option(value, label, note) for value, label, note in options],
+                title=title, default=default - 1,
+            )
+            if picked is not None:
+                return picked
+            # The list could not run, or was escaped out of. Either way the
+            # question still needs an answer, so the numbered form takes over.
+
         table = Table.grid(padding=(0, 2))
         table.add_column(justify="right", no_wrap=True)
         table.add_column(no_wrap=True)
@@ -124,6 +187,7 @@ class SetupWizard:
             self.console.print(
                 Text("  Not needed — this one runs on your machine.",
                      style=self.theme.style("dim")))
+            self._answered("api key", "not needed")
 
         answers.model = self._ask_model(3, total, spec, answers)
         answers.approvals = self._ask_approvals(4, total)
@@ -152,7 +216,9 @@ class SetupWizard:
             Text("  You can add more later; this is just the one to start with.\n",
                  style=self.theme.style("dim")))
         options = [(spec.id, spec.label, spec.blurb) for spec in catalogue.offered()]
-        return self._choose(options, default=1)
+        chosen = self._choose(options, default=1, title="Providers")
+        self._answered("provider", dict((v, l) for v, l, _ in options).get(chosen, chosen))
+        return chosen
 
     def _ask_endpoint(self) -> str:
         self.console.print()
@@ -175,24 +241,33 @@ class SetupWizard:
             # off screen recordings.
             key = self._secret("  key (input hidden): ").strip()
             if key:
+                self._answered("api key", "set, and never shown again")
                 return key
             self.console.print(Text("  a key is required for this provider",
                                     style=self.theme.style("bad")))
 
     def _ask_model(self, step: int, total: int,
                    spec: catalogue.ProviderSpec | None, answers: Answers) -> str:
-        self._rule("Which model?", step, total)
-
+        # Discovery first, and the question afterwards, because asking the
+        # provider what it has takes a second or two over the network. During
+        # that second the terminal is still in its ordinary mode, so anything
+        # impatient fingers press is echoed — an arrow key arrives on screen as
+        # `^[[B` and sits there. Clearing for the question is what wipes it, so
+        # the clearing has to come second. The keystrokes themselves are
+        # discarded when the reader takes the terminal.
         models = self._discover_models(spec, answers)
+
+        self._rule("Which model?", step, total)
         if not models:
             return self._ask("model id", spec.default_model if spec else "")
 
         options = [(model, model, "recommended" if index == 0 else "")
                    for index, model in enumerate(models)]
         options.append(("__other__", "something else", "type the model id"))
-        chosen = self._choose(options, default=1)
+        chosen = self._choose(options, default=1, title="Models")
         if chosen == "__other__":
-            return self._ask("model id", models[0])
+            chosen = self._ask("model id", models[0])
+        self._answered("model", chosen)
         return chosen
 
     def _discover_models(self, spec: catalogue.ProviderSpec | None,
@@ -231,16 +306,17 @@ class SetupWizard:
 
     def _ask_approvals(self, step: int, total: int) -> str:
         self._rule("How much should it ask before acting?", step, total)
-        return self._choose(
-            [
-                ("ask", "Ask before writing or running anything",
-                 "safest; you see a diff or the command first"),
-                ("writes", "Write files freely, ask before running commands",
-                 "a good middle ground"),
-                ("auto", "Do not ask", "fastest; everything is still checkpointed"),
-            ],
-            default=1,
-        )
+        options = [
+            ("ask", "Ask before writing or running anything",
+             "safest; you see a diff or the command first"),
+            ("writes", "Write files freely, ask before running commands",
+             "a good middle ground"),
+            ("auto", "Do not ask", "fastest; everything is still checkpointed"),
+        ]
+        chosen = self._choose(options, default=1, title="Approvals")
+        self._answered("approvals",
+                       dict((v, l) for v, l, _ in options).get(chosen, chosen))
+        return chosen
 
     # -- applying --------------------------------------------------------- #
 

comodor-0.2.2/src/comodor/ui/chooser.py

@@ -0,0 +1,271 @@
+"""Choosing from a list, with the arrow keys.
+
+The wizard used to print a numbered list and read a number. That is fine for
+three options and wrong for a hundred: picking a model meant reading a wall of
+identifiers, finding the one you wanted, remembering its number, scrolling back
+down because the list had pushed the prompt off the screen, and typing a digit
+you were no longer sure of. And every question stayed on screen afterwards, so
+by the fourth one the terminal was a transcript of decisions already made.
+
+What is here instead is one framed list at a time.
+
+* **The frame never grows past the terminal.** However many options there are,
+  the list is windowed to what will fit and moves with the cursor, with a count
+  of what is above and below. Nothing is ever off screen with no sign that it
+  is there.
+* **Typing filters.** With sixty models on offer, `son` is faster than sixty
+  presses of the down arrow, and it is what anybody who has used a fuzzy finder
+  will try first.
+* **It refuses to be the only way in.** Without a terminal — a pipe, a test, an
+  editor's console, `curl | sh` — the numbered prompt is still there. A setup
+  wizard that requires a particular kind of terminal is a setup wizard that
+  cannot be scripted.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Sequence
+
+from rich.console import Console, Group, RenderableType
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+from .input.keys import KeyEvent
+from .input.reader import TerminalInput
+from .theme import Theme
+
+#: Rows the frame spends on itself: two borders, and the hint line under it.
+CHROME = 4
+#: Never show fewer than this, even on a very short terminal.
+MIN_ROWS = 3
+
+
+@dataclass(frozen=True)
+class Option:
+    value: str
+    label: str
+    note: str = ""
+
+    def matches(self, needle: str) -> bool:
+        return needle in self.label.lower() or needle in self.note.lower()
+
+
+def interactive(console: Console) -> bool:
+    """Can we take over the keyboard here?"""
+    try:
+        return bool(console.is_terminal and console.file.isatty()
+                    and _stdin_is_a_terminal())
+    except Exception:
+        return False
+
+
+def _stdin_is_a_terminal() -> bool:
+    import sys
+
+    try:
+        return bool(sys.stdin and sys.stdin.isatty())
+    except Exception:
+        return False
+
+
+class Chooser:
+    """One list, one choice."""
+
+    def __init__(self, console: Console, theme: Theme, options: Sequence[Option],
+                 title: str = "", default: int = 0) -> None:
+        self.console = console
+        self.theme = theme
+        self.options = list(options)
+        self.title = title
+        self.cursor = max(0, min(default, len(self.options) - 1))
+        self.filter = ""
+        self.offset = 0
+
+    # -- what is currently visible ---------------------------------------- #
+
+    @property
+    def matching(self) -> list[Option]:
+        if not self.filter:
+            return self.options
+        needle = self.filter.lower()
+        return [option for option in self.options if option.matches(needle)]
+
+    def rows(self) -> int:
+        """How many options fit, given the terminal we are in."""
+        available = max(MIN_ROWS, self.console.size.height - CHROME - 6)
+        return min(len(self.matching) or 1, available)
+
+    def _scroll_into_view(self) -> None:
+        window = self.rows()
+        if self.cursor < self.offset:
+            self.offset = self.cursor
+        elif self.cursor >= self.offset + window:
+            self.offset = self.cursor - window + 1
+        self.offset = max(0, min(self.offset, max(0, len(self.matching) - window)))
+
+    # -- drawing ----------------------------------------------------------- #
+
+    def render(self) -> RenderableType:
+        theme = self.theme
+        items = self.matching
+        window = self.rows()
+        self._scroll_into_view()
+        visible = items[self.offset:self.offset + window]
+
+        table = Table.grid(padding=(0, 1))
+        table.add_column(width=2, no_wrap=True)
+        table.add_column(no_wrap=True)
+        table.add_column(overflow="ellipsis")
+
+        if not items:
+            table.add_row("", Text("nothing matches", style=theme.style("bad")),
+                          Text(""))
+
+        for index, option in enumerate(visible, start=self.offset):
+            chosen = index == self.cursor
+            # The arrow, not just a colour: a highlighted row that relies on
+            # background alone disappears on a terminal that renders it faintly,
+            # and this is the only thing on screen saying where you are.
+            table.add_row(
+                Text(theme.glyphs.arrow if chosen else " ",
+                     style=theme.style("accent", bold=True)),
+                Text(option.label,
+                     style=theme.style("accent" if chosen else "value",
+                                       bold=chosen)),
+                Text(option.note, style=theme.style("dim")),
+            )
+
+        blocks: list[RenderableType] = []
+        above = self.offset
+        below = max(0, len(items) - self.offset - window)
+        if above:
+            blocks.append(Text(f"  {above} more above", style=theme.style("dim")))
+        blocks.append(table)
+        if below:
+            blocks.append(Text(f"  {below} more below", style=theme.style("dim")))
+
+        subtitle = None
+        if self.filter:
+            subtitle = Text(f" filter: {self.filter} ", style=theme.style("accent"))
+        elif len(items) != len(self.options):
+            subtitle = Text(f" {len(items)} of {len(self.options)} ",
+                            style=theme.style("dim"))
+
+        panel = Panel(
+            Group(*blocks),
+            box=self.theme.box,
+            border_style=theme.style("border"),
+            title=Text(f" {self.title} ", style=theme.style("title")) if self.title
+            else None,
+            title_align="left",
+            subtitle=subtitle,
+            subtitle_align="right",
+            padding=(0, 1),
+        )
+        return Group(panel, self._hint())
+
+    def _hint(self) -> Text:
+        theme = self.theme
+        hint = Text("  ", style=theme.style("dim"))
+        for key, what in (("↑↓", "move"), ("enter", "choose"),
+                          ("type", "filter"), ("esc", "cancel")):
+            hint.append(key, style=theme.style("accent"))
+            hint.append(f" {what}   ", style=theme.style("dim"))
+        return hint
+
+    # -- the loop ----------------------------------------------------------- #
+
+    def run(self) -> str | None:
+        """Returns the chosen value, or None if the user backed out."""
+        from rich.live import Live
+
+        items = self.matching
+        if not items:
+            return None
+
+        with TerminalInput(mouse=False, paste=False) as terminal, Live(
+            self.render(), console=self.console, auto_refresh=False,
+            transient=True,
+        ) as live:
+            while True:
+                event = terminal.wait(0.2)
+                if event is None:
+                    continue
+                if not isinstance(event, KeyEvent):
+                    continue
+
+                outcome = self._handle(event)
+                if outcome is _CANCEL:
+                    return None
+                if outcome is not None:
+                    return outcome
+                live.update(self.render(), refresh=True)
+
+    def _handle(self, event: KeyEvent) -> object:
+        """None to keep going, a string to accept it, ``_CANCEL`` to give up."""
+        items = self.matching
+
+        if event.matches("ctrl+c") or event.key == "escape":
+            return _CANCEL
+        if event.key == "enter":
+            return items[self.cursor].value if items else _CANCEL
+
+        if event.key in ("up", "down", "pgup", "pgdn", "home", "end"):
+            self._move(event.key, len(items))
+            return None
+        if event.key == "backspace":
+            self.filter = self.filter[:-1]
+            self._reset_cursor()
+            return None
+        if event.key == "char" and event.char and not event.ctrl and not event.alt:
+            self.filter += event.char
+            self._reset_cursor()
+            return None
+        return None
+
+    def _move(self, key: str, count: int) -> None:
+        if count == 0:
+            return
+        window = self.rows()
+        if key == "up":
+            # Wrapping, because a list that stops dead at the top makes you
+            # reach for the mouse to get to the bottom of a long one.
+            self.cursor = (self.cursor - 1) % count
+        elif key == "down":
+            self.cursor = (self.cursor + 1) % count
+        elif key == "pgup":
+            self.cursor = max(0, self.cursor - window)
+        elif key == "pgdn":
+            self.cursor = min(count - 1, self.cursor + window)
+        elif key == "home":
+            self.cursor = 0
+        elif key == "end":
+            self.cursor = count - 1
+
+    def _reset_cursor(self) -> None:
+        """A changed filter means a changed list; start at the top of it."""
+        self.cursor = 0
+        self.offset = 0
+
+
+class _Cancel:
+    pass
+
+
+_CANCEL = _Cancel()
+
+
+def choose(console: Console, theme: Theme, options: Sequence[Option],
+           title: str = "", default: int = 0) -> str | None:
+    """The whole interaction, or None if there is no terminal to run it in."""
+    if not interactive(console) or not options:
+        return None
+    try:
+        return Chooser(console, theme, options, title=title, default=default).run()
+    except Exception:
+        # A terminal that will not do raw mode, a reader that will not start:
+        # the caller still has the numbered prompt, and a failed experiment
+        # must not cost somebody their first run.
+        return None

comodor-0.2.2/tests/test_chooser.py

@@ -0,0 +1,208 @@
+"""Moving through a list with the arrow keys.
+
+The behaviour that matters is not "does Enter return something" — it is what
+happens when the list is longer than the terminal, which is the case this
+replaces. So most of what is checked here is the window: that the cursor is
+always inside it, that the counts above and below add up, and that filtering
+does not leave the cursor pointing at a row that is no longer there.
+
+The key handler is driven directly with `KeyEvent`s. Nothing here opens a
+terminal, because the decoder that turns escape sequences into those events is
+already tested on its own in `test_input.py`, and a test that needs a real
+keyboard is a test that does not run in CI.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from comodor.ui import theme as theme_module
+from comodor.ui.chooser import Chooser, Option, choose
+from comodor.ui.console import build
+from comodor.ui.input.keys import KeyEvent
+
+
+def make(count: int = 40, height: int = 24) -> Chooser:
+    theme = theme_module.load("ember")
+    console = build(theme, width=80, height=height)
+    options = [Option(f"m{i}", f"model-{i:02d}", "recommended" if i == 0 else "")
+               for i in range(count)]
+    return Chooser(console, theme, options, title="Models")
+
+
+def press(chooser: Chooser, *keys: str) -> object:
+    outcome = None
+    for key in keys:
+        event = KeyEvent("char", char=key) if len(key) == 1 and key.isalnum() \
+            else KeyEvent(key)
+        outcome = chooser._handle(event)
+        chooser.render()          # what the loop does between keystrokes
+    return outcome
+
+
+# --------------------------------------------------------------------------- #
+# the window
+# --------------------------------------------------------------------------- #
+
+
+def test_a_long_list_is_windowed_to_the_terminal():
+    chooser = make(count=200, height=24)
+    chooser.render()
+
+    assert chooser.rows() < 200
+    assert chooser.rows() <= 24
+
+
+def test_the_cursor_never_leaves_the_window():
+    chooser = make(count=200, height=24)
+
+    for _ in range(150):
+        press(chooser, "down")
+        assert chooser.offset <= chooser.cursor < chooser.offset + chooser.rows()
+
+
+def test_what_is_above_and_below_adds_up():
+    chooser = make(count=60, height=24)
+    press(chooser, *(["down"] * 30))
+    window = chooser.rows()
+
+    above = chooser.offset
+    below = len(chooser.matching) - chooser.offset - window
+
+    assert above + window + below == 60
+    assert above > 0 and below > 0
+
+
+def test_the_ends_wrap():
+    """A list that stops dead at the top sends you looking for the mouse."""
+    chooser = make(count=10)
+
+    press(chooser, "up")
+    assert chooser.cursor == 9
+
+    press(chooser, "down")
+    assert chooser.cursor == 0
+
+
+def test_home_and_end_and_the_page_keys():
+    chooser = make(count=100, height=24)
+
+    press(chooser, "end")
+    assert chooser.cursor == 99
+
+    press(chooser, "home")
+    assert chooser.cursor == 0
+
+    press(chooser, "pgdn")
+    assert chooser.cursor == chooser.rows()
+
+
+def test_a_short_list_needs_no_window():
+    chooser = make(count=3, height=40)
+    chooser.render()
+
+    assert chooser.rows() == 3
+    assert chooser.offset == 0
+
+
+# --------------------------------------------------------------------------- #
+# filtering
+# --------------------------------------------------------------------------- #
+
+
+def test_typing_narrows_the_list():
+    chooser = make(count=40)
+
+    press(chooser, "3")
+    assert chooser.filter == "3"
+    # model-03, model-13, model-23, model-30..39
+    assert all("3" in option.label for option in chooser.matching)
+    assert 0 < len(chooser.matching) < 40
+
+
+def test_backspace_widens_it_again():
+    chooser = make(count=40)
+    press(chooser, "3", "backspace")
+
+    assert chooser.filter == ""
+    assert len(chooser.matching) == 40
+
+
+def test_a_changed_filter_puts_the_cursor_back_at_the_top():
+    """Otherwise it points at a row that is no longer in the list."""
+    chooser = make(count=40)
+    press(chooser, *(["down"] * 20))
+    assert chooser.cursor == 20
+
+    press(chooser, "7")
+
+    assert chooser.cursor == 0
+    assert chooser.cursor < len(chooser.matching)
+
+
+def test_a_filter_that_matches_nothing_says_so_and_returns_nothing():
+    chooser = make(count=10)
+    press(chooser, "z", "z", "z")
+
+    assert chooser.matching == []
+    assert "nothing matches" in _text(chooser)
+    # Enter on an empty list cannot invent an answer.
+    from comodor.ui.chooser import _CANCEL
+
+    assert chooser._handle(KeyEvent("enter")) is _CANCEL
+
+
+def test_the_filter_reads_the_note_as_well_as_the_label():
+    chooser = make(count=10)
+    press(chooser, "r", "e", "c")
+
+    assert [option.value for option in chooser.matching] == ["m0"]
+
+
+# --------------------------------------------------------------------------- #
+# choosing, and not choosing
+# --------------------------------------------------------------------------- #
+
+
+def test_enter_returns_the_row_under_the_cursor():
+    chooser = make(count=10)
+    press(chooser, "down", "down")
+
+    assert chooser._handle(KeyEvent("enter")) == "m2"
+
+
+def test_enter_returns_the_row_under_the_cursor_after_filtering():
+    """The cursor indexes the filtered list, not the original one."""
+    chooser = make(count=40)
+    press(chooser, "1", "2")
+
+    assert chooser._handle(KeyEvent("enter")) == "m12"
+
+
+@pytest.mark.parametrize("event", [KeyEvent("escape"), KeyEvent("c", ctrl=True)])
+def test_backing_out_returns_nothing(event):
+    from comodor.ui.chooser import _CANCEL
+
+    assert make()._handle(event) is _CANCEL
+
+
+def test_without_a_terminal_there_is_no_list_to_drive():
+    """The caller falls back to the numbered prompt, which always works."""
+    theme = theme_module.load("ember")
+    console = build(theme, width=80, height=24)
+
+    assert choose(console, theme, [Option("a", "A")], title="x") is None
+
+
+def test_ctrl_and_alt_combinations_are_not_typed_into_the_filter():
+    chooser = make(count=10)
+    chooser._handle(KeyEvent("char", char="k", ctrl=True))
+
+    assert chooser.filter == ""
+
+
+def _text(chooser: Chooser) -> str:
+    console = chooser.console
+    with console.capture() as captured:
+        console.print(chooser.render())
+    return captured.get()