feat(runner): add results command to inspect Robot Framework runs

After running tests, `robotcode results` lets you explore the output
without opening `report.html` or re-running the suite — handy for CI
logs, agent-driven workflows, and quick failure inspection from the
terminal.

Three subcommands:

- `robotcode results summary` — overall status, pass/fail/skip counts,
  run duration, and the total number of error and warning messages.
  `--failures` adds the list of failed tests above the counts.
- `robotcode results show` — one line per test with its status, source
  link, and failure message. Filter by status, tags, suite or test
  name pattern.
- `robotcode results log` — the full execution tree: every keyword
  call, control structure, and log message, just like Robot's
  `report.html` but in your terminal. `--failures-only`, `--level
  WARN`, `--extract DIR` (pulls out screenshots and embedded
  artefacts), and more.

The output file is auto-discovered from your active `robot.toml`
profile; override with `-o/--output PATH`. Test names carry a
`(path:line)` suffix that VS Code's integrated terminal turns into a
clickable goto-source link. Pass `--format json` (or `toml`) for a
structured, agent-friendly payload.

See `docs/03_reference/cli.md` and `robotcode results --help` for the
full reference.

Author: d-biehl

docs/03_reference/cli.md

@@ -240,21 +240,19 @@ def print_data(
                 if format == OutputFormat.JSON_INDENT:
                     format = OutputFormat.JSON
                 console = Console(soft_wrap=True)
-                if self.config.pager:
+                syntax = Syntax(text, format, background_color="default")
+                if self._should_page(lambda: text.count("\n")):
                     with console.pager(styles=True, links=True):
-                        console.print(Syntax(text, format, background_color="default"))
+                        console.print(syntax)
                 else:
-                    console.print(Syntax(text, format, background_color="default"))
+                    console.print(syntax)
 
                 return
             except ImportError:
                 if self.config.colored_output == ColoredOutput.YES:
                     self.warning('Package "rich" is required to use colored output.')
 
-        if self.config.pager:
-            self.echo_via_pager(text)
-        else:
-            self.echo(text)
+        self.echo_via_pager(text)
 
         return
 
@@ -273,6 +271,30 @@ def echo(
             err=err,
         )
 
+    def _should_page(self, measure_lines: Callable[[], int]) -> bool:
+        """Tri-state pager decision.
+
+        - `config.pager` is True  → always page.
+        - `config.pager` is False → never page.
+        - `config.pager` is None  → auto: page only when stdout is a TTY AND
+                                     the rendered output exceeds the terminal
+                                     height (measured via the callback).
+        """
+        pref = self.config.pager
+        if pref is True:
+            return True
+        if pref is False:
+            return False
+        if not sys.stdout.isatty():
+            return False
+        try:
+            from shutil import get_terminal_size
+
+            term_lines = get_terminal_size(fallback=(80, 24)).lines
+            return measure_lines() > term_lines - 2
+        except Exception:
+            return False
+
     def echo_as_markdown(self, text: str) -> None:
         if self.colored:
             try:
@@ -307,7 +329,14 @@ def __rich_console__(self, console: Console, options: ConsoleOptions) -> RenderR
                 markdown = Markdown(text, justify="left", code_theme="default")
 
                 console = Console()
-                if self.config.pager:
+
+                def _measure() -> int:
+                    measure = Console(width=console.size.width, record=False, soft_wrap=True)
+                    with measure.capture() as cap:
+                        measure.print(markdown)
+                    return cap.get().count("\n")
+
+                if self._should_page(_measure):
                     with console.pager(styles=True, links=True):
                         console.print(markdown)
                 else:
@@ -325,18 +354,20 @@ def echo_via_pager(
         color: Optional[bool] = None,
     ) -> None:
         try:
-            if not self.config.pager:
-                text = (
-                    text_or_generator
-                    if isinstance(text_or_generator, str)
-                    else "".join(text_or_generator() if callable(text_or_generator) else text_or_generator)
-                )
-                click.echo(text, color=color if color is not None else self.colored)
+            text = (
+                text_or_generator
+                if isinstance(text_or_generator, str)
+                else "".join(text_or_generator() if callable(text_or_generator) else text_or_generator)
+            )
+            use_color = color if color is not None else self.colored
+            if self._should_page(lambda: text.count("\n")):
+                if use_color:
+                    # click only sets `LESS=-R` when color=None — set it here so
+                    # less renders ANSI styles instead of showing raw ESC codes.
+                    os.environ.setdefault("LESS", "-R")
+                click.echo_via_pager(text, color=use_color)
             else:
-                click.echo_via_pager(
-                    text_or_generator,
-                    color=color if color is not None else self.colored,
-                )
+                click.echo(text, color=use_color)
         except OSError:
             pass
 

packages/plugin/src/robotcode/plugin/__init__.py

@@ -35,6 +35,9 @@ dependencies = [
   "robotcode",
 ]
 
+[project.optional-dependencies]
+html = ["html-to-markdown>=2.0"]
+
 [project.entry-points.robotcode]
 runner = "robotcode.runner.hooks"
 

packages/runner/pyproject.toml

@@ -1,7 +1,8 @@
 from .discover import discover
 from .libdoc import libdoc
 from .rebot import rebot
+from .results import results
 from .robot import robot
 from .testdoc import testdoc
 
-__all__ = ["discover", "libdoc", "rebot", "robot", "testdoc"]
+__all__ = ["discover", "libdoc", "rebot", "results", "robot", "testdoc"]

packages/runner/src/robotcode/runner/cli/__init__.py

@@ -0,0 +1,3 @@
+from .results import results
+
+__all__ = ["results"]