robotcode-repl 2.6.2__py3-none-any.whl → 2.8.0.dev548__py3-none-any.whl

robotcode/repl/console_interpreter.py

@@ -24,28 +24,33 @@ import shlex
 import sys
 from datetime import datetime
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, Callable, Dict, Iterator, List, Optional, Set, Tuple, TypeVar, Union
+from typing import TYPE_CHECKING, Any, Callable, Dict, Iterator, List, Optional, Set, Tuple, TypeVar, Union, cast
 
 import click
 from robot import result, running
+from robot.errors import ExecutionFailed, ExecutionPassed
 from robot.running import Keyword
 from robot.running.context import EXECUTION_CONTEXTS
+from robot.utils import normalize
 
 from robotcode.plugin import Application
 from robotcode.robot.diagnostics.library_doc import (
+    MARKDOWN_DOC_FORMAT,
     REST_DOC_FORMAT,
     ROBOT_DOC_FORMAT,
     LibraryDoc,
     convert_from_rest,
+    get_docstring_info,
     get_library_doc_from_library,
     get_resource_doc_from_resource,
 )
-from robotcode.robot.utils import get_robot_version_str
+from robotcode.robot.utils import RF_VERSION, get_robot_version_str
+from robotcode.robot.utils.markdown_docs import LinkResolver, anchor_link_resolver, normalize_markdown_doc
 from robotcode.robot.utils.markdownformatter import MarkDownFormatter
 
 from .__version__ import __version__
-from ._debug.types import Breakpoint, ResumeAction, StackFrame, StopEvent
-from ._indent import compute_indent
+from ._debug.types import Breakpoint, ResumeAction, StackFrame, StopEvent, StopReason
+from ._indent import compute_indent, starts_with_continuation
 from ._keyword_lookup import (
     _LIB_KEYWORDS_ATTR,
     iter_keyword_owners,
@@ -54,7 +59,7 @@ from ._keyword_lookup import (
     lookup_resource,
 )
 from ._session_export import render_robot_file
-from .base_interpreter import BaseInterpreter, is_true
+from .base_interpreter import BaseInterpreter, ReplInput, is_true
 
 if TYPE_CHECKING:
     from ._debug.controller import DebugController
@@ -91,6 +96,19 @@ _SETTING_IMPORT_ALIASES = {
     "variables": "Import Variables",
 }
 
+# Robot Framework 5.0 fails an invalid TRY without logging why; later versions log it.
+if RF_VERSION < (6, 0):
+    from robot.running.model import Try as _RunningTry
+
+    def _unlogged_error(item: Any) -> Optional[str]:
+        return cast(Optional[str], item.error) if isinstance(item, _RunningTry) else None
+
+else:
+
+    def _unlogged_error(item: Any) -> Optional[str]:
+        return None
+
+
 # `.help` groups, in display order. A command's group is set on `@dot_command`.
 _GROUP_ORDER = ("Session", "Debugger")
 
@@ -120,36 +138,58 @@ def dot_command(name: str, *aliases: str, group: str = "Session") -> Callable[[F
     return decorator
 
 
-# Variables that Robot itself sets in every suite — filtered out by
-# `.vars --user` so the listing focuses on what the user assigned.
-# Robot's built-in variables, matched by exact name or a `<PREFIX>_` / `<PREFIX> `
-# boundary (see `_is_robot_internal`) so a user variable like `${TESTDATA}` is NOT
-# mistaken for an internal one just because it starts with `TEST`.
-_ROBOT_INTERNAL_PREFIXES = (
-    "CURDIR",
-    "DEBUG_FILE",
-    "EXECDIR",
-    "FAILED",
-    "KEYWORD",
-    "LOG",
-    "OPTIONS",
-    "OUTPUT",
-    "PASSED",
-    "PREV",
-    "REPORT",
-    "ROBOT",
-    "SPACE",
-    "SUITE",
-    "TASK",
-    "TEMPDIR",
-    "TEST",
-    "TIMEOUT",
+# The variables Robot Framework sets itself, normalized the way Robot compares
+# variable names (case, spaces and underscores ignored). `.vars --user` hides
+# them so the listing focuses on what the session or the suite defined.
+# `${\n}` is a backslash followed by `n`.
+_ROBOT_BUILTIN_VARIABLES = frozenset(
+    normalize(name, ignore="_")
+    for name in (
+        "/",
+        ":",
+        "\\n",
+        "SPACE",
+        "True",
+        "False",
+        "None",
+        "null",
+        "TEMPDIR",
+        "EXECDIR",
+        "OPTIONS",
+        "OUTPUT_DIR",
+        "OUTPUT_FILE",
+        "REPORT_FILE",
+        "LOG_FILE",
+        "DEBUG_FILE",
+        "LOG_LEVEL",
+        "PREV_TEST_NAME",
+        "PREV_TEST_STATUS",
+        "PREV_TEST_MESSAGE",
+        "SUITE_NAME",
+        "SUITE_SOURCE",
+        "SUITE_DOCUMENTATION",
+        "SUITE_METADATA",
+        "SUITE_STATUS",
+        "SUITE_MESSAGE",
+        "TEST_NAME",
+        "TEST_TAGS",
+        "TEST_DOCUMENTATION",
+        "TEST_METADATA",
+        "TEST_STATUS",
+        "TEST_MESSAGE",
+        "KEYWORD_STATUS",
+        "KEYWORD_MESSAGE",
+    )
 )
 
 
-def _is_robot_internal(bare: str) -> bool:
-    """Whether a bare variable name is one of Robot's built-ins (boundary match)."""
-    return any(bare == p or bare.startswith((p + "_", p + " ")) for p in _ROBOT_INTERNAL_PREFIXES)
+def _is_robot_internal(name: str) -> bool:
+    """Whether a variable such as `${SUITE_NAME}` is one that Robot Framework sets itself,
+    or the REPL's result variable `${_}` (see `set_last_result`)."""
+    bare = name[2:-1] if len(name) > 2 and name[0] in "$@&%" and name[1] == "{" and name[-1] == "}" else name
+    normalized = normalize(bare, ignore="_")
+    # `${_}` normalizes to an empty name.
+    return not normalized or normalized in _ROBOT_BUILTIN_VARIABLES
 
 
 # Destructive commands that must never be reachable via prefix abbreviation — only
@@ -167,6 +207,8 @@ def _format_doc_to_md(text: str, doc_format: str) -> str:
         return MarkDownFormatter().format(text)
     if doc_format == REST_DOC_FORMAT:
         return convert_from_rest(text)
+    if doc_format == MARKDOWN_DOC_FORMAT:
+        return normalize_markdown_doc(text)
     return text
 
 
@@ -194,13 +236,18 @@ def _diagnostics_keyword_doc(owner: Any, is_resource: bool, kw_name: str) -> Opt
     return matches[0] if matches else None
 
 
-def _render_runtime_keyword_md(kw: Any, kw_name: str) -> str:
+def _render_runtime_keyword_md(kw: Any, kw_name: str, is_resource: bool = False) -> str:
     """Hand-built fallback keyword page for resources / dynamic libs.
 
     Used only when the diagnostics loader can't surface a `KeywordDoc`
     for this keyword. Renders name + signature + tags + doc + source
     in a shape close to what `KeywordDoc.to_markdown` produces.
     """
+    try:
+        # splits the `Tags:` and, with Robot Framework 7.5, the `Args:`/`Returns:`/`Raises:` sections off
+        info = get_docstring_info(kw, kw, is_resource)
+    except Exception:
+        info = None
     md: List[str] = [f"### {kw_name}", ""]
 
     spec = getattr(kw, "args", None) or getattr(kw, "arguments", None)
@@ -213,12 +260,22 @@ def _render_runtime_keyword_md(kw: Any, kw_name: str) -> str:
             md.append(f"`{kw_name}    {sig}`")
             md.append("")
 
-    tags = list(getattr(kw, "tags", None) or [])
+    if info is not None:
+        for name, description in (info.argument_docs or {}).items():
+            md.append(f"- `{name}`: {description}")
+        if info.return_doc:
+            md.extend(["", f"**Returns**: {info.return_doc}"])
+        for name, description in info.raises or []:
+            md.extend(["", f"**Raises** `{name}`: {description}"])
+        if info.argument_docs or info.return_doc or info.raises:
+            md.append("")
+
+    tags = info.tags if info is not None else list(getattr(kw, "tags", None) or [])
     if tags:
         md.append("_Tags: " + ", ".join(str(t) for t in tags) + "_")
         md.append("")
 
-    doc = getattr(kw, "doc", None) or ""
+    doc = (info.doc if info is not None else getattr(kw, "doc", None)) or ""
     if doc:
         md.append(_format_doc_to_md(doc, getattr(kw, "doc_format", ROBOT_DOC_FORMAT)))
 
@@ -257,6 +314,7 @@ def _build_save_parser() -> argparse.ArgumentParser:
     p = argparse.ArgumentParser(prog=".save", add_help=False, exit_on_error=False)
     p.add_argument("-a", "--append", action="store_true", help="Append to FILENAME instead of overwriting.")
     p.add_argument("-t", "--test-name", default="", help="Override the generated test-case name.")
+    p.add_argument("--keep-failed", action="store_true", help="Also export inputs whose run failed.")
     p.add_argument("filename")
     return p
 
@@ -303,6 +361,15 @@ class ConsoleInterpreter(BaseInterpreter):
         # REPL inputs that parsed cleanly — `.save` exports them as a
         # runnable `.robot` file. Each entry may be multi-line.
         self._session_lines: List[str] = []
+        # Indexes into `_session_lines` of inputs whose run failed; `.save`
+        # leaves them out unless `--keep-failed` is given.
+        self._failed_session_lines: Set[int] = set()
+        # Set when the input ended inside an unfinished block: that block still
+        # runs, then the session ends without reading again — on a terminal, a
+        # read after Ctrl-D waits for more input instead of ending.
+        self._input_ended = False
+        # Set while a prompt waits for input: SIGTERM then ends the wait (`_end_waiting`).
+        self._reading = False
 
         # Debug-frontend state. `_controller`/`_debug_completer` are wired by
         # `set_controller` when a debugger is attached; `_stop`/`_frame_no`/
@@ -416,6 +483,78 @@ class ConsoleInterpreter(BaseInterpreter):
         del multiline_continuation, prefill, completer  # no editor/prefill/completion in plain mode
         return input(prompt)
 
+    def _read(self, prompt: str, **kwargs: Any) -> str:
+        """`read_line` that SIGTERM can end: it raises `EOFError` once the session or run
+        is to end, also while it waits."""
+        self._reading = True
+        try:
+            # Checked after marking the read: a SIGTERM in between can't be missed.
+            if self._termination_requested:
+                raise EOFError
+            return self.read_line(prompt, **kwargs)
+        finally:
+            self._reading = False
+
+    def _end_waiting(self) -> None:
+        # Nothing pauses any more, so a robot-debug run goes on to its end.
+        if self._controller is not None:
+            self._controller.set_attached(False)
+        if self._reading:
+            self._end_read()
+
+    def _end_read(self) -> None:
+        """End the read that waits for input, from the signal handler."""
+        raise EOFError
+
+    def _interrupt_waiting(self) -> None:
+        # The plain backend reads with `input()`, which sees Ctrl-C only as this signal; the prompts expect
+        # KeyboardInterrupt from Ctrl-C.
+        if self._reading:
+            raise KeyboardInterrupt
+
+    def _pause_on_interrupt(self) -> bool:
+        controller = self._controller
+        if (
+            controller is None
+            or not controller.attached
+            or controller.pause_requested  # a second Ctrl-C interrupts the keyword that runs
+            or self._stop is not None  # at a stop, Ctrl-C interrupts a keyword typed there
+            # The debugger sees the keywords of a robot-debug run, and in a REPL session those of a statement.
+            or not self._logger.enabled
+            or (self._in_repl_run and not self._running_statement)
+        ):
+            return False
+        controller.request_pause()
+        if self.app is not None:
+            try:
+                # To the console, past Robot Framework's capture of what a running keyword prints, and on a line of
+                # its own, as the console output of the run can be in the middle of one.
+                self.app.echo(
+                    "\nPausing at the next keyword (Ctrl-C again interrupts the keyword that runs).",
+                    file=sys.__stdout__,
+                )
+            except Exception:
+                # The signal can interrupt a write to the same stream, which then refuses this one; the pause stays
+                # requested.
+                pass
+        return True
+
+    def _interrupt_ends_run(self) -> bool:
+        # A robot-debug run (events forwarded outside a REPL session) without the debugger ends as a robot run
+        # does; REPL sessions, also while they start, keep their handling.
+        return (
+            self._logger.enabled
+            and not self._in_repl_run
+            and (self._controller is None or not self._controller.attached)
+        )
+
+    def _report_interrupt(self, prompt: str) -> None:
+        """Report Ctrl-C at a prompt as Python's REPL does. `input()` leaves the cursor after the prompt, so the
+        line of a shown prompt is ended first."""
+        if prompt:
+            self._echo("")
+        self._echo("KeyboardInterrupt")
+
     def make_completer(
         self, command_names: List[str], context_provider: Callable[[], Tuple[Any, Any]]
     ) -> Optional[Any]:
@@ -424,17 +563,18 @@ class ConsoleInterpreter(BaseInterpreter):
         del command_names, context_provider
         return None
 
-    def show_doc(self, title: str, markdown: str, *, scroll_to: Optional[str] = None) -> None:
+    def show_doc(self, title: str, markdown: str, *, scroll_to: Optional[str] = None, outline: bool = False) -> None:
         """Display markdown to the user.
 
         Plain mode pages the raw markdown source with colour off — the
         backend choice signals "low-fi terminal", so we don't surface
         rich-rendered markdown the user explicitly opted out of. The
         prompt_toolkit interpreter overrides this with the scrollable
-        doc-viewer Float. ``scroll_to`` is honoured only by that viewer;
-        the pager ignores it.
+        doc-viewer Float. ``scroll_to`` and ``outline`` (a sidebar with the
+        headings of a library page) are honoured only by that viewer; the
+        pager ignores them.
         """
-        del scroll_to  # only the scrollable viewer (prompt_toolkit) uses it
+        del scroll_to, outline  # only the scrollable viewer (prompt_toolkit) uses them
         body = f"{title}\n{'=' * len(title)}\n\n{markdown}"
         if self.app is not None:
             self.app.echo_via_pager(body, color=False)
@@ -464,6 +604,25 @@ class ConsoleInterpreter(BaseInterpreter):
         self.set_last_result(None)
         return super().run()
 
+    def run_input(self) -> None:
+        recorded = len(self._session_lines)
+        try:
+            super().run_input()
+        except ExecutionPassed as e:
+            # `Pass Execution` ends the input successfully, unless failures were
+            # continued before it — Robot Framework fails the test then.
+            if e.earlier_failures:
+                self._failed_session_lines.update(range(recorded, len(self._session_lines)))
+            raise
+        except BaseException:
+            # A failure, `Skip` or an interrupt: the input didn't run through.
+            self._failed_session_lines.update(range(recorded, len(self._session_lines)))
+            raise
+        finally:
+            # A pause that Ctrl-C asked for and the input didn't reach must not stop the next input.
+            if self._controller is not None:
+                self._controller.cancel_pause()
+
     # ------------------------------------------------------------------
     # Debug frontend — the interpreter *is* the debug core's `Frontend`.
     # A pause calls `wait_at_stop`, which renders the stop and runs a
@@ -488,15 +647,17 @@ class ConsoleInterpreter(BaseInterpreter):
         Dot-commands route through the shared dispatcher; the debugger
         commands (`.continue`/`.step`/…) set `_pending_action`, which ends
         the loop. Anything else is evaluated as a keyword in the paused
-        context. EOF / Ctrl-C at the prompt continues the run.
+        context. EOF (Ctrl-D) at the prompt continues the run; Ctrl-C drops
+        the typed input and prompts again, as in pdb.
         """
         self._stop = stop
         self._frame_no = 0  # innermost frame selected
         self._pending_action = None
         # A breakpoint with attached `.commands` replays them at the hit; a
-        # leading `silent` suppresses the stop banner (pdb semantics).
+        # leading `silent` suppresses the stop banner (pdb semantics), except
+        # when it carries a condition error (a breakpoint stop's only description).
         bp = stop.breakpoint
-        silent = bool(bp is not None and bp.commands and bp.commands[0] == "silent")
+        silent = bool(bp is not None and bp.commands and bp.commands[0] == "silent" and not stop.description)
         if not silent:
             self._render_stop(stop)
         # try/finally so the stop state is always cleared, even if `.abort`
@@ -508,8 +669,12 @@ class ConsoleInterpreter(BaseInterpreter):
                 self._replay_commands(bp.commands)
             while self._pending_action is None:
                 try:
-                    line = self.read_line(self.DEBUG_PROMPT, completer=self._debug_completer)
-                except (EOFError, KeyboardInterrupt):
+                    line = self._read(self.DEBUG_PROMPT, completer=self._debug_completer)
+                except KeyboardInterrupt:
+                    # Ctrl-C drops what was typed, as in pdb; the run stays paused.
+                    self._report_interrupt(self.DEBUG_PROMPT)
+                    continue
+                except EOFError:
                     self._echo("")
                     self._pending_action = ResumeAction.CONTINUE
                     break
@@ -679,6 +844,11 @@ class ConsoleInterpreter(BaseInterpreter):
         don't re-trigger a stop, and in `forward_events(echo_messages=True)` so
         its log output surfaces at the prompt (suite output is muted otherwise).
         """
+        # At the end of a suite Robot Framework has already closed the suite in
+        # output.xml when we stop; a keyword written after it makes the file unreadable.
+        if self._stop is not None and self._stop.reason == StopReason.EXCEPTION and self._stop.frame.type == "SUITE":
+            self._echo("! Keywords can't run at the end of a suite: its output is already closed.")
+            return
         try:
             test, errors = self.get_test_body_from_string(line)
         except Exception as e:  # surface any parse failure to the prompt
@@ -690,9 +860,14 @@ class ConsoleInterpreter(BaseInterpreter):
             return
         if not test.body:
             return
-        with self._controller.suppress_pausing(), self.forward_events(echo_messages=True):  # type: ignore[union-attr]
-            for kw in test.body:
-                self.set_last_result(self.run_keyword(kw))
+        # Keywords evaluated at a stop don't count for the session status.
+        record_failures, self.record_failures = self.record_failures, False
+        try:
+            with self._controller.suppress_pausing(), self.forward_events(echo_messages=True):  # type: ignore[union-attr]
+                for kw in test.body:
+                    self.set_last_result(self.run_keyword(kw))
+        finally:
+            self.record_failures = record_failures
         self._echo(f"=> {_repr.repr(self.last_result)}")
 
     # ------------------------------------------------------------------
@@ -733,6 +908,15 @@ class ConsoleInterpreter(BaseInterpreter):
                 if target is not None:
                     item.name = target
 
+    def _body_to_run(self, parsed: ReplInput) -> Iterator[Keyword]:
+        """The statements of `parsed` to run, with the setting-import aliases applied."""
+        self._alias_setting_imports(parsed.test)
+        for item in parsed.test.body:
+            error = _unlogged_error(item)
+            if error:
+                self.log_message(error, "FAIL")
+            yield item
+
     def get_input(self) -> Iterator[Optional[Keyword]]:
         if self.executed_files and not self.files and not self.inspect:
             raise EOFError
@@ -744,14 +928,12 @@ class ConsoleInterpreter(BaseInterpreter):
 
             text = file.read_text(encoding="utf-8")
 
-            test, errors = self.get_test_body_from_string(text)
-            if errors:
-                return
-
-            self._alias_setting_imports(test)
-            for kw in test.body:
-                yield kw
+            # Run like a test body: an invalid statement fails when execution reaches it.
+            yield from self._body_to_run(self.parse_input(text))
         else:
+            if self._input_ended:
+                raise EOFError
+
             lines: List[str] = []
             last_one = False
             while True:
@@ -761,7 +943,7 @@ class ConsoleInterpreter(BaseInterpreter):
 
                 prefill = compute_indent(lines) if lines else ""
                 try:
-                    text = self.read_line(
+                    text = self._read(
                         prompt,
                         multiline_continuation=bool(lines),
                         prefill=prefill,
@@ -775,31 +957,47 @@ class ConsoleInterpreter(BaseInterpreter):
                         if self._dispatch_dot_command(text):
                             return
                 except KeyboardInterrupt:
-                    if len(lines) > 0:
-                        lines = []
-                        last_one = False
-                        continue
-                    raise
+                    # Ctrl-C drops what was typed, as in Python's REPL; the session goes on.
+                    self._report_interrupt(prompt)
+                    lines = []
+                    last_one = False
+                    continue
+                except EOFError:
+                    if not lines or self._termination_requested:
+                        raise
+                    # Handle the unfinished block like after a final empty line, so
+                    # Robot Framework reports it, and end the session afterwards.
+                    self._input_ended = True
+                    text = ""
+                    # The report starts on a line of its own, not after the prompt.
+                    if prompt:
+                        self._echo("")
+
+                if not lines and starts_with_continuation(text):
+                    # At the start of an input there is nothing left to continue.
+                    message = "The line starting with '...' does not continue a statement, it starts a new input."
+                    self.log_message(message, "FAIL")
+                    raise ExecutionFailed(message)
 
                 lines.append(text)
 
-                test, errors = self.get_test_body_from_string("\n".join(lines))
+                parsed = self.parse_input("\n".join(lines))
 
                 if len(lines) > 1 and lines[-1] == "" and text == "":
                     last_one = True
 
-                if errors:
-                    if not last_one:
-                        continue
+                # Only an unfinished block waits for more lines; complete input runs
+                # even when it is invalid, so Robot Framework reports it.
+                if parsed.incomplete and not last_one:
+                    continue
 
-                # Record cleanly-parsed inputs for `.save`. Error-only
-                # inputs are skipped so the exported file stays runnable.
-                if test.body:
+                # Record cleanly-parsed inputs for `.save` (`run_input` marks the
+                # ones whose run fails). Inputs with errors are skipped so the
+                # exported file stays runnable.
+                if parsed.test.body and not parsed.errors:
                     self._session_lines.append("\n".join(lines))
 
-                self._alias_setting_imports(test)
-                for kw in test.body:
-                    yield kw
+                yield from self._body_to_run(parsed)
 
                 break
 
@@ -973,28 +1171,26 @@ class ConsoleInterpreter(BaseInterpreter):
 
         Options:
           --user   Hide Robot's built-in variables (`${SUITE_NAME}`,
-                   `${OUTPUT_DIR}`, `${TEMPDIR}`, …) so the listing focuses
-                   on what the user assigned in the session. Has no effect at a
-                   debug stop, where variables are grouped by scope instead.
+                   `${OUTPUT_DIR}`, `${TEMPDIR}`, `${True}`, …) and the
+                   result variable `${_}` so the listing focuses on what the
+                   session or the suite defined. At a debug stop it filters
+                   every scope of the listing.
         """
         if self.app is None:
             return
+        only_user = "--user" in arg.split()
         if self._stop is not None:
-            self._show_frame_scopes()
+            self._show_frame_scopes(only_user)
             return
         ctx = EXECUTION_CONTEXTS.current
         if ctx is None:
             self.app.echo("(no active context)")
             return
-        only_user = "--user" in arg.split()
 
         rows: List[Tuple[str, str]] = []
         for decorated, value in ctx.variables.as_dict().items():
             name = str(decorated)
-            bare = name
-            if len(name) > 2 and name[0] in "$@&%" and name[1] == "{" and name[-1] == "}":
-                bare = name[2:-1]
-            if only_user and _is_robot_internal(bare):
+            if only_user and _is_robot_internal(name):
                 continue
             try:
                 rep = repr(value)
@@ -1011,7 +1207,7 @@ class ConsoleInterpreter(BaseInterpreter):
         for name, rep in rows:
             self.app.echo(f"  {name:<{name_w}}  {rep}")
 
-    def _show_frame_scopes(self) -> None:
+    def _show_frame_scopes(self, only_user: bool) -> None:
         """`.vars` at a debug stop — the selected frame's scopes, via the controller."""
         scopes = self._controller.get_scopes(self._selected_frame()) if self._controller is not None else []
         if not scopes:
@@ -1019,9 +1215,10 @@ class ConsoleInterpreter(BaseInterpreter):
             return
         for scope in scopes:
             self._echo(f"{scope.name}:")
-            if not scope.variables:
+            variables = [v for v in scope.variables if not (only_user and _is_robot_internal(v.name))]
+            if not variables:
                 self._echo("    (none)")
-            for var in scope.variables:
+            for var in variables:
                 self._echo(f"    {var.name} = {var.value}")
 
     @dot_command("kw")
@@ -1076,8 +1273,16 @@ class ConsoleInterpreter(BaseInterpreter):
         kw_name = getattr(runtime_kw, "name", name)
         diag_kw = _diagnostics_keyword_doc(owner, is_resource, kw_name)
         if diag_kw is not None:
-            return kw_name, diag_kw.to_markdown(header_level=1)
-        return kw_name, _render_runtime_keyword_md(runtime_kw, kw_name)
+            link_resolver = self._keyword_link_resolver(str(getattr(owner, "name", "")))
+            return kw_name, diag_kw.to_markdown(header_level=1, link_resolver=link_resolver)
+        return kw_name, _render_runtime_keyword_md(runtime_kw, kw_name, is_resource)
+
+    def _keyword_link_resolver(self, owner_name: str) -> Optional[LinkResolver]:
+        """Where references in a keyword page go. Nothing can be followed here,
+        so they stay inline code; the prompt_toolkit backend overrides this to
+        link to the pages of other keywords."""
+        del owner_name
+        return None
 
     def _list_keywords(self, pattern: Optional[str]) -> None:
         """List loaded keywords grouped by owner, optionally filtered by a
@@ -1149,7 +1354,11 @@ class ConsoleInterpreter(BaseInterpreter):
             self.app.echo(error or f"Could not load {arg!r}.")
             return
 
-        self.show_doc(lib_doc.name, lib_doc.to_markdown(only_doc=False, header_level=1))
+        self.show_doc(
+            lib_doc.name,
+            lib_doc.to_markdown(only_doc=False, header_level=0, link_resolver=anchor_link_resolver),
+            outline=True,
+        )
 
     def _resolve_doc_target(self, arg: str) -> Tuple[Optional[LibraryDoc], Optional[str]]:
         """Build the `LibraryDoc` for an imported library or resource.
@@ -1193,9 +1402,11 @@ class ConsoleInterpreter(BaseInterpreter):
     def _cwd(self, arg: str) -> None:
         """Show the current working directory.
 
-        Print the current working directory — the base path that relative
-        `Import Resource`, `Import Library`, and file-based variable
-        references resolve against.
+        Print the working directory of the REPL process — the project root.
+        Relative file paths passed to keywords such as `File Should Exist`
+        resolve against it. `${CURDIR}` and, on Robot Framework 7.4 and newer,
+        relative imports use the directory of `--source` instead, or the
+        directory the REPL was started from if `--source` isn't given.
         """
         del arg
         if self.app is None:
@@ -1207,32 +1418,48 @@ class ConsoleInterpreter(BaseInterpreter):
 
     @dot_command("exit", "quit")
     def _exit(self, arg: str) -> None:
-        """Exit the REPL.
+        """Exit the REPL: .exit [CODE]
 
-        Leave the REPL. Equivalent to pressing Ctrl-D on an empty prompt.
+        Leave the REPL. Without CODE this is the same as pressing Ctrl-D on
+        an empty prompt. With CODE, `robotcode repl` exits with that exit code
+        instead of the one it derives from the session status.
         `.exit` and `.quit` are aliases. At a debug stop "exit" is ambiguous,
         so it points you at the resume/abort commands instead of leaving.
+
+        Usage:
+          .exit [CODE]
+
+        Examples:
+          .exit
+          .exit 3
         """
-        del arg
         if self._stop is not None:
             self._echo("at a debug stop — use .continue or .detach to resume, or .abort to quit the run")
             return
+        if arg:
+            try:
+                self.exit_code = int(arg)
+            except ValueError:
+                self._echo("Usage: .exit [CODE]")
+                return
         raise EOFError
 
     @dot_command("save")
     def _save(self, arg: str) -> None:
-        """Save session as a .robot file: .save [-a] [-t NAME] FILENAME
+        """Save session as a .robot file: .save [-a] [-t NAME] [--keep-failed] FILENAME
 
-        Save the current REPL session as a runnable `.robot` file. Only
-        lines Robot could parse are exported; lines that failed are
-        skipped so the result stays runnable with `robot <filename>`.
+        Save the current REPL session as a runnable `.robot` file. Inputs
+        with syntax errors are never exported. Inputs whose run failed or
+        was skipped are left out too, so the result runs with
+        `robot <filename>` the way the session did; `--keep-failed` keeps
+        them.
 
         Imports become a `*** Settings ***` section (so
         `Import Library    Collections` becomes `Library    Collections`),
         and everything else goes into a single `*** Test Cases ***` block.
 
         Usage:
-          .save [-a] [-t NAME] FILENAME
+          .save [-a] [-t NAME] [--keep-failed] FILENAME
 
         Options:
           -a, --append             Append to FILENAME instead of overwriting.
@@ -1243,6 +1470,8 @@ class ConsoleInterpreter(BaseInterpreter):
                                    Override the default test-case name. By
                                    default the test is called
                                    `REPL Session <ISO-timestamp>`.
+          --keep-failed            Also export inputs whose run failed,
+                                   e.g. to reproduce a failing check.
 
         Examples:
           .save scratch.robot
@@ -1255,13 +1484,17 @@ class ConsoleInterpreter(BaseInterpreter):
         try:
             opts = parser.parse_args(_split_command_args(arg))
         except (argparse.ArgumentError, SystemExit, ValueError):
-            self.app.echo("Usage: .save [-a] [-t NAME] FILENAME")
+            self.app.echo("Usage: .save [-a] [-t NAME] [--keep-failed] FILENAME")
             return
 
-        lines: List[str] = list(self._session_lines or [])
-        if not lines:
+        recorded: List[str] = list(self._session_lines or [])
+        if not recorded:
             self.app.echo("Nothing to save — the session has no recorded inputs yet.")
             return
+        lines = [line for i, line in enumerate(recorded) if opts.keep_failed or i not in self._failed_session_lines]
+        if not lines:
+            self.app.echo("Nothing to save — every recorded input failed; `--keep-failed` exports them anyway.")
+            return
 
         content = render_robot_file(lines, test_name=opts.test_name)
         path = Path(opts.filename)
@@ -1280,7 +1513,11 @@ class ConsoleInterpreter(BaseInterpreter):
             self.app.echo(f"Could not write {opts.filename}: {e}")
             return
 
-        self.app.echo(f"Wrote {path} ({len(lines)} entries)")
+        summary = f"{len(lines)} {'entry' if len(lines) == 1 else 'entries'}"
+        left_out = len(recorded) - len(lines)
+        if left_out:
+            summary += f"; {left_out} failed {'input' if left_out == 1 else 'inputs'} left out, see --keep-failed"
+        self.app.echo(f"Wrote {path} ({summary})")
 
     # ------------------------------------------------------------------
     # Debugger dot-commands — active while paused at a stop (`group=
@@ -1520,13 +1757,16 @@ class ConsoleInterpreter(BaseInterpreter):
 
     @dot_command("set", group="Debugger")
     def _set(self, arg: str) -> None:
-        """Set a scalar variable in the selected frame — `.set ${x} <value>`.
-
-        The value is variable-substituted and stored as-is (like `Set Variable`):
-        `.set ${name} hello` sets the string; use `${{ ... }}` for Python. Only
-        whole scalar variables (`${...}`) are supported — not list/dict variables
-        (`@{...}`/`&{...}`) or item access (`${x}[0]`). The assignment lands in
-        the selected frame's local scope.
+        """Change an existing scalar variable in the selected frame — `.set ${x} <value>`.
+
+        Only variables that already exist can be changed; create a new one with
+        `${x}=    Set Variable    …` at the prompt. The value is
+        variable-substituted and stored as a string: `.set ${name} hello` sets
+        `hello`, and `.set ${count} 7` sets the string `7`. For other types,
+        assign at the prompt, e.g. `${items}=    Evaluate    [1, 2]`. Only whole
+        scalar variables (`${...}`) are supported — not list/dict variables
+        (`@{...}`/`&{...}`) or item access (`${x}[0]`). The value lands in the
+        selected frame's local scope.
         """
         if not self._require_stop():
             return
@@ -1574,7 +1814,7 @@ class ConsoleInterpreter(BaseInterpreter):
 
     @dot_command("break", "b", group="Debugger")
     def _break(self, arg: str) -> None:
-        """Add a breakpoint — `.break file:line` / `.break Keyword Name` / `.break <loc>, <condition>`."""
+        """Add a breakpoint — `.break file:line` / `.break Keyword Name or pattern` / `.break <loc>, <condition>`."""
         self._add_breakpoint(arg, temporary=False)
 
     @dot_command("tbreak", group="Debugger")
@@ -1605,7 +1845,7 @@ class ConsoleInterpreter(BaseInterpreter):
             if bp.log_message is not None:
                 flags.append("logpoint")
             if bp.commands:
-                flags.append(f"{len(bp.commands)} cmds")
+                flags.append(f"{len(bp.commands)} {'cmd' if len(bp.commands) == 1 else 'cmds'}")
             suffix = ("  " + ", ".join(flags)) if flags else ""
             self._echo(f"  #{bp.id}  {bp.kind:<7} {loc}{suffix}")
         filters = controller.exception_filters
@@ -1735,8 +1975,13 @@ class ConsoleInterpreter(BaseInterpreter):
         collected: List[str] = []
         while True:
             try:
-                line = self.read_line("(com) ")
-            except (EOFError, KeyboardInterrupt):
+                line = self._read("(com) ")
+            except KeyboardInterrupt:
+                # Ctrl-C aborts the entry, as in pdb; the breakpoint keeps its commands.
+                self._report_interrupt("(com) ")
+                self._echo(f"breakpoint {bp.id}: commands unchanged")
+                return
+            except EOFError:
                 break
             line = line.strip()
             if line == "end":