feat(repl): browse and search keywords from .kw

`.kw` does more than show a single keyword now. With no argument it
lists every keyword you have imported, grouped by the library or
resource it comes from. With text that isn't an exact keyword name it
lists the keywords whose name contains that text, so you can find a
keyword without remembering its full name or leaving the REPL. Giving an
exact keyword name still shows that keyword's full documentation as
before.

In the interactive documentation viewer the listed keyword names are
links: Tab to one and press Enter to open its documentation, and press
`[` to go back to the list — the same navigation the cross-reference
links inside a library page already use. On the plain backend the list
comes back as text.

Author: d-biehl

packages/repl/src/robotcode/repl/_keyword_lookup.py

@@ -12,7 +12,7 @@
 synchronously inside `suite.run()`.
 """
 
-from typing import Any, List, Optional, Tuple
+from typing import Any, Iterator, List, Optional, Tuple
 
 from robot.running.context import EXECUTION_CONTEXTS
 from robot.utils import normalize
@@ -139,6 +139,25 @@ def _find_keyword_in_owner(owner: Any, normalized_name: str) -> Optional[Any]:
     return None
 
 
+def iter_keyword_owners() -> Iterator[Tuple[str, bool, List[str]]]:
+    """Yield ``(owner_name, is_resource, keyword_names)`` for each loaded
+    library and resource, libraries first. ``keyword_names`` is sorted.
+    Used to list / search what the session has imported.
+    """
+    store = _current_kw_store()
+    if store is None:
+        return
+    for owner in store.libraries.values():
+        yield str(owner.name), False, _keyword_names(owner)
+    for owner in store.resources.values():
+        yield str(owner.name), True, _keyword_names(owner)
+
+
+def _keyword_names(owner: Any) -> List[str]:
+    names = [str(kw.name) for kw in (getattr(owner, _LIB_KEYWORDS_ATTR, ()) or ()) if getattr(kw, "name", None)]
+    return sorted(names)
+
+
 def lookup_library(name: str) -> Optional[Any]:
     """The loaded library instance named ``name``, or ``None``.
 

packages/repl/src/robotcode/repl/_pt/doc_viewer.py

@@ -269,6 +269,22 @@ class _RenderSnapshot(NamedTuple):
     anchor_to_line: Dict[str, int]
 
 
+class _NavState(NamedTuple):
+    """One entry in the back / forward navigation stacks.
+
+    Captures everything needed to return to a position the user was at:
+    the document itself (`title` + `md_source`) plus the scroll offset
+    and focused link. Carrying the source means a follow that loaded a
+    *different* document — e.g. a keyword page opened from a list — can
+    be reversed by reloading the previous document, not just scrolling.
+    """
+
+    title: str
+    md_source: str
+    scroll: int
+    current_link: int
+
+
 # Viewer-only style entries. The host interpreter's `_DEFAULT_STYLE`
 # is for the prompt + log output; the viewer is its own Application
 # with its own narrow palette, so we don't grow `_pt.components` for
@@ -459,7 +475,14 @@ class DocViewer:
     prompt's scrollback is undisturbed.
     """
 
-    def __init__(self) -> None:
+    def __init__(
+        self,
+        link_resolver: Optional[Callable[[str], Optional[Tuple[str, str]]]] = None,
+    ) -> None:
+        # Resolves a followed link target that is neither an `#anchor`
+        # nor an `http(s)://` URL into new `(title, markdown)` content,
+        # loaded in place. Used to open a keyword's page from a list.
+        self._link_resolver = link_resolver
         self._title = ""
 
         # Body content: stored as fragments so we can re-render with
@@ -489,14 +512,13 @@ def __init__(self) -> None:
         self._current_link = -1
         self._anchor_to_line: Dict[str, int] = {}
 
-        # Browser-style back / forward stacks for `#anchor` follows.
-        # Each entry is `(vertical_scroll, current_link)`; only the
-        # scroll position + focused link are restored, search state
-        # is intentionally untouched (going back shouldn't drop the
-        # user's current search). External URL follows don't push
-        # since the viewer itself doesn't move.
-        self._back_stack: List[Tuple[int, int]] = []
-        self._forward_stack: List[Tuple[int, int]] = []
+        # Browser-style back / forward stacks for `#anchor` jumps and
+        # in-place content follows (see `_NavState`). Search state is
+        # intentionally untouched on back/forward (going back shouldn't
+        # drop the user's current search). External URL follows don't
+        # push since the viewer itself doesn't move.
+        self._back_stack: List[_NavState] = []
+        self._forward_stack: List[_NavState] = []
 
         # Resize state. `_md_source` keeps the markdown around so we
         # can re-render at the new width when the terminal resizes.
@@ -601,6 +623,28 @@ def run(self, title: str, markdown: str) -> None:
         screen buffer, so the host prompt's terminal state survives
         the call untouched.
         """
+        # A fresh top-level invocation starts with empty history.
+        self._back_stack = []
+        self._forward_stack = []
+        self._load_document(title, markdown)
+
+        try:
+            self._app.run()
+        finally:
+            # Don't leak a pending reflow callback into the next
+            # `.doc` invocation — if it fired against a closed app
+            # the invalidate() at the end would be a no-op, but the
+            # state shuffle would still run.
+            if self._resize_task is not None:
+                self._resize_task.cancel()
+                self._resize_task = None
+
+    def _load_document(self, title: str, markdown: str) -> None:
+        """Adopt ``markdown`` as the current document and reset per-doc
+        state (scroll, focused link, search). Leaves the back / forward
+        stacks alone so it can be reused for in-place link follows;
+        `run` clears them for a fresh top-level invocation.
+        """
         self._title = title
         self._md_source = markdown
         # New doc → all cached renders are for the OLD markdown. Wipe.
@@ -610,27 +654,25 @@ def run(self, title: str, markdown: str) -> None:
         body_width = max(size.columns - 2, 40)
         self._render_at_width(body_width)
 
-        # Reset interaction state for a fresh document.
         self._current_link = -1
-        self._back_stack = []
-        self._forward_stack = []
         self._in_search_mode = False
         self._search_query = ""
         self._matches = []
         self._current_match = -1
         self._search_buffer.reset()
         self._body_window.vertical_scroll = 0
 
-        try:
-            self._app.run()
-        finally:
-            # Don't leak a pending reflow callback into the next
-            # `.doc` invocation — if it fired against a closed app
-            # the invalidate() at the end would be a no-op, but the
-            # state shuffle would still run.
-            if self._resize_task is not None:
-                self._resize_task.cancel()
-                self._resize_task = None
+    def _current_state(self) -> _NavState:
+        """Snapshot the current document + position for the nav stacks."""
+        return _NavState(self._title, self._md_source, self._body_window.vertical_scroll, self._current_link)
+
+    def _restore_state(self, state: _NavState) -> None:
+        """Return to a `_NavState`, reloading its document first if the
+        current one differs."""
+        if state.md_source != self._md_source:
+            self._load_document(state.title, state.md_source)
+        self._body_window.vertical_scroll = state.scroll
+        self._current_link = state.current_link
 
     def _render_at_width(self, body_width: int) -> None:
         """Render the markdown at ``body_width`` and adopt the result.
@@ -923,21 +965,22 @@ def _follow_current_link(self) -> None:
         didn't match the markdown source title). For `http(s)://`
         targets, hand off to the OS's default browser via
         `webbrowser.open` — caught so an SSH session or headless
-        environment can't take the viewer down.
-
-        Anchor jumps push the current scroll + focused link onto the
-        back stack so `[` returns to the previous position
-        (browser-style). The forward stack is cleared because the
-        new jump branches the history. External URL follows don't
-        push — the viewer didn't move.
+        environment can't take the viewer down. Any other target is
+        handed to `link_resolver` (if configured); when it returns
+        content, that document is loaded in place.
+
+        Anchor jumps and content follows push the current position onto
+        the back stack so `[` returns to it (browser-style). The forward
+        stack is cleared because the new jump branches the history.
+        External URL follows don't push — the viewer didn't move.
         """
         if self._current_link < 0 or not self._links:
             return
         _start, _end, target = self._links[self._current_link]
         if target.startswith("#"):
             line = self._anchor_to_line.get(target[1:])
             if line is not None:
-                self._back_stack.append((self._body_window.vertical_scroll, self._current_link))
+                self._back_stack.append(self._current_state())
                 self._forward_stack.clear()
                 # `_max_scroll()` returns 0 before the first render —
                 # only clamp when we have real render_info, otherwise
@@ -949,31 +992,34 @@ def _follow_current_link(self) -> None:
                 webbrowser.open(target)
             except Exception:
                 pass
+        elif self._link_resolver is not None:
+            resolved = self._link_resolver(target)
+            if resolved is not None:
+                self._back_stack.append(self._current_state())
+                self._forward_stack.clear()
+                self._load_document(resolved[0], resolved[1])
 
     def _go_back(self) -> bool:
-        """Restore the previous scroll position from the back stack.
+        """Return to the previous position from the back stack.
 
         Returns True if there was something to restore (so the
         keybinding can decide whether to invalidate the layout).
         Symmetric with `_go_forward` — pushing the *current* state
         onto the opposite stack before popping, so back→forward
-        round-trips return the user to where they were.
+        round-trips return the user to where they were. The previous
+        document is reloaded if a content follow had replaced it.
         """
         if not self._back_stack:
             return False
-        self._forward_stack.append((self._body_window.vertical_scroll, self._current_link))
-        scroll, link = self._back_stack.pop()
-        self._body_window.vertical_scroll = scroll
-        self._current_link = link
+        self._forward_stack.append(self._current_state())
+        self._restore_state(self._back_stack.pop())
         return True
 
     def _go_forward(self) -> bool:
         if not self._forward_stack:
             return False
-        self._back_stack.append((self._body_window.vertical_scroll, self._current_link))
-        scroll, link = self._forward_stack.pop()
-        self._body_window.vertical_scroll = scroll
-        self._current_link = link
+        self._back_stack.append(self._current_state())
+        self._restore_state(self._forward_stack.pop())
         return True
 
     # ------------------------------------------------------------------

packages/repl/src/robotcode/repl/console_interpreter.py

@@ -36,7 +36,13 @@
 
 from .__version__ import __version__
 from ._indent import compute_indent
-from ._keyword_lookup import _LIB_KEYWORDS_ATTR, lookup_keyword_owner, lookup_library, lookup_resource
+from ._keyword_lookup import (
+    _LIB_KEYWORDS_ATTR,
+    iter_keyword_owners,
+    lookup_keyword_owner,
+    lookup_library,
+    lookup_resource,
+)
 from ._session_export import render_robot_file
 from .base_interpreter import BaseInterpreter, is_true
 
@@ -595,48 +601,95 @@ def _vars(self, arg: str) -> None:
 
     @dot_command("kw")
     def _kw(self, arg: str) -> None:
-        """Show the documentation for a keyword: .kw <name>
+        """Show or search keyword documentation: .kw [name-or-text]
 
-        Shows the keyword's signature (arguments with their types and
-        defaults), description, tags, and where it comes from.
+        With a keyword name, shows its full documentation: signature
+        (arguments with their types and defaults), description, tags, and
+        where it comes from. Names are resolved just like in a Robot
+        Framework suite, so the `Owner.Keyword` form works too.
 
-        Names are resolved just like in a Robot Framework suite, so the
-        `Owner.Keyword` form works too when the same name comes from more
-        than one imported library or resource.
+        With no argument, lists every keyword grouped by the library or
+        resource it belongs to. With text that isn't an exact keyword
+        name, lists the keywords whose name contains that text.
 
         Usage:
-          .kw <keyword-name>
+          .kw                 list every loaded keyword
+          .kw <text>          list keywords whose name contains <text>
+          .kw <keyword-name>  show full documentation for one keyword
 
         Examples:
-          .kw Log
+          .kw
+          .kw append
           .kw Get From Dictionary
           .kw BuiltIn.Log
         """
         if self.app is None:
             return
         if not arg:
-            self.app.echo("Usage: .kw <keyword-name>")
+            self._list_keywords(None)
             return
-        found = lookup_keyword_owner(arg)
-        if found is None:
-            self.app.echo(f"No keyword found: {arg!r}")
+
+        doc = self._keyword_doc(arg)
+        if doc is None:
+            # Not an exact keyword — treat the argument as a search filter.
+            self._list_keywords(arg)
             return
-        owner, runtime_kw, is_resource = found
+        self.show_doc(*doc)
 
-        kw_name = getattr(runtime_kw, "name", arg)
+    def _keyword_doc(self, name: str) -> Optional[Tuple[str, str]]:
+        """`(title, markdown)` for an exactly-named keyword, or ``None``.
 
-        # Prefer the diagnostics `KeywordDoc` — it carries
-        # `to_markdown(...)` with proper signature + arg table + types,
-        # which the runtime keyword object (`StaticKeyword`) doesn't.
+        Shared by `.kw <name>` and the doc-viewer link resolver. Prefers
+        the diagnostics `KeywordDoc` (proper signature + arg table +
+        types); falls back to a hand-built page from the runtime object
+        when that conversion can't surface one.
+        """
+        found = lookup_keyword_owner(name)
+        if found is None:
+            return None
+        owner, runtime_kw, is_resource = found
+        kw_name = getattr(runtime_kw, "name", name)
         diag_kw = _diagnostics_keyword_doc(owner, is_resource, kw_name)
         if diag_kw is not None:
-            self.show_doc(kw_name, diag_kw.to_markdown(header_level=1))
+            return kw_name, diag_kw.to_markdown(header_level=1)
+        return kw_name, _render_runtime_keyword_md(runtime_kw, kw_name)
+
+    def _list_keywords(self, pattern: Optional[str]) -> None:
+        """List loaded keywords grouped by owner, optionally filtered by a
+        case-insensitive substring of the keyword name."""
+        if self.app is None:
+            return
+        needle = pattern.casefold() if pattern else None
+
+        sections: List[str] = []
+        total = 0
+        for owner_name, is_resource, names in iter_keyword_owners():
+            if needle is not None:
+                names = [n for n in names if needle in n.casefold()]
+            if not names:
+                continue
+            kind = "Resource" if is_resource else "Library"
+            sections.append(f"## {owner_name} ({kind})")
+            sections.extend(self._keyword_list_entry(owner_name, n) for n in names)
+            sections.append("")
+            total += len(names)
+
+        if total == 0:
+            if pattern:
+                self.app.echo(f"No keywords found matching {pattern!r}.")
+            else:
+                self.app.echo("(no keywords loaded)")
             return
 
-        # Fallback for keywords the diagnostics conversion can't surface
-        # — hand-build a minimal page from whatever the runtime object
-        # exposes.
-        self.show_doc(kw_name, _render_runtime_keyword_md(runtime_kw, kw_name))
+        title = f"Keywords matching '{pattern}'" if pattern else "Keywords"
+        self.show_doc(title, f"# {title}\n\n" + "\n".join(sections))
+
+    def _keyword_list_entry(self, owner_name: str, kw_name: str) -> str:
+        """One bullet line for `_list_keywords`. Plain text here; the
+        prompt_toolkit backend overrides this to emit a follow-able link
+        into the keyword's documentation."""
+        del owner_name
+        return f"- {kw_name}"
 
     @dot_command("doc")
     def _doc(self, arg: str) -> None: