UAT: `format_output()` with `rich` format silently falls back to JSON — should use rich/color renderer #3999

New issue

Open

opened 2026-04-06 08:26:02 +00:00 by freemo · 0 comments

freemo commented

2026-04-06 08:26:02 +00:00

Owner

Metadata

Branch: fix/cli-format-output-rich-color-renderer
Commit Message: fix(cli): implement rich and color renderers in format_output()
Milestone: None (Backlog)
Parent Epic: #936

Backlog note: This issue was discovered during autonomous operation
on milestone v3.5.0. It does not block milestone completion and has been
placed in the backlog for human review and future milestone assignment.

Background and Context

The format_output() function in src/cleveragents/cli/formatting.py is the public API for rendering CLI output in a requested format. The Output Rendering Framework (spec §Output Rendering Framework) defines format-specific renderers including a rich renderer for interactive terminal output and a color renderer for ANSI-colored output. The current implementation silently falls back to incorrect formats for both rich and color, making the API unreliable when called directly.

Current Behavior

In src/cleveragents/cli/formatting.py, the format_output() function (lines ~190–200) contains:

# ``rich`` and any unknown value fall back to JSON
return _format_json(safe_data)

And for the color format:

if fmt == OutputFormat.COLOR.value:
    return _format_plain(safe_data)

This means:

format_output(data, "rich") returns JSON output instead of rich terminal output
format_output(data, "color") returns plain text instead of ANSI-colored output

Most CLI commands work around this by checking if fmt != OutputFormat.RICH.value: before calling format_output, but the function itself is incorrect and misleading as a public API.

Expected Behavior

format_output(data, "rich") should render rich terminal output using _format_table or the rich/color renderer (delegating to the rich library or the OutputSession Rich materializer)
format_output(data, "color") should render ANSI-colored output (not plain text)

Per spec §Output Rendering Framework, each format must have a correct renderer. Silent fallback to an unrelated format violates the principle of least surprise and makes the API contract unreliable.

Code Location

File: src/cleveragents/cli/formatting.py
Function: format_output()
Lines: ~190–200

Subtasks

Implement _format_rich() in formatting.py that renders output using the rich library (tables, panels, or delegates to _format_table)
Implement _format_color() in formatting.py that renders output with ANSI color codes (not plain text)
Wire OutputFormat.RICH → _format_rich() in the format_output() dispatch
Wire OutputFormat.COLOR → _format_color() in the format_output() dispatch
Remove the silent JSON fallback comment and replace with an explicit ValueError for truly unknown formats
Add Behave BDD scenarios to verify format_output(data, "rich") returns rich-formatted output
Add Behave BDD scenarios to verify format_output(data, "color") returns ANSI-colored output (not plain text)
Verify coverage >= 97% via nox -s coverage_report
Run nox (all default sessions), fix any errors

Definition of Done

All subtasks completed and checked off
format_output(data, "rich") produces rich terminal output (not JSON)
format_output(data, "color") produces ANSI-colored output (not plain text)
Unknown format values raise ValueError instead of silently falling back to JSON
BDD tests cover both rich and color format paths in format_output()
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional details
The commit is pushed to the remote on the branch matching the Branch in Metadata exactly
The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done
All nox stages pass
Coverage >= 97%

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-new-issue-creator

## Metadata - **Branch**: `fix/cli-format-output-rich-color-renderer` - **Commit Message**: `fix(cli): implement rich and color renderers in format_output()` - **Milestone**: None (Backlog) - **Parent Epic**: #936 > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.5.0. It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. ## Background and Context The `format_output()` function in `src/cleveragents/cli/formatting.py` is the public API for rendering CLI output in a requested format. The Output Rendering Framework (spec §Output Rendering Framework) defines format-specific renderers including a `rich` renderer for interactive terminal output and a `color` renderer for ANSI-colored output. The current implementation silently falls back to incorrect formats for both `rich` and `color`, making the API unreliable when called directly. ## Current Behavior In `src/cleveragents/cli/formatting.py`, the `format_output()` function (lines ~190–200) contains: ```python # ``rich`` and any unknown value fall back to JSON return _format_json(safe_data) ``` And for the `color` format: ```python if fmt == OutputFormat.COLOR.value: return _format_plain(safe_data) ``` This means: - `format_output(data, "rich")` returns **JSON output** instead of rich terminal output - `format_output(data, "color")` returns **plain text** instead of ANSI-colored output Most CLI commands work around this by checking `if fmt != OutputFormat.RICH.value:` before calling `format_output`, but the function itself is incorrect and misleading as a public API. ## Expected Behavior - `format_output(data, "rich")` should render rich terminal output using `_format_table` or the rich/color renderer (delegating to the `rich` library or the OutputSession Rich materializer) - `format_output(data, "color")` should render ANSI-colored output (not plain text) Per spec §Output Rendering Framework, each format must have a correct renderer. Silent fallback to an unrelated format violates the principle of least surprise and makes the API contract unreliable. ## Code Location - **File**: `src/cleveragents/cli/formatting.py` - **Function**: `format_output()` - **Lines**: ~190–200 ## Subtasks - [ ] Implement `_format_rich()` in `formatting.py` that renders output using the `rich` library (tables, panels, or delegates to `_format_table`) - [ ] Implement `_format_color()` in `formatting.py` that renders output with ANSI color codes (not plain text) - [ ] Wire `OutputFormat.RICH` → `_format_rich()` in the `format_output()` dispatch - [ ] Wire `OutputFormat.COLOR` → `_format_color()` in the `format_output()` dispatch - [ ] Remove the silent JSON fallback comment and replace with an explicit `ValueError` for truly unknown formats - [ ] Add Behave BDD scenarios to verify `format_output(data, "rich")` returns rich-formatted output - [ ] Add Behave BDD scenarios to verify `format_output(data, "color")` returns ANSI-colored output (not plain text) - [ ] Verify coverage >= 97% via `nox -s coverage_report` - [ ] Run `nox` (all default sessions), fix any errors ## Definition of Done - [ ] All subtasks completed and checked off - [ ] `format_output(data, "rich")` produces rich terminal output (not JSON) - [ ] `format_output(data, "color")` produces ANSI-colored output (not plain text) - [ ] Unknown format values raise `ValueError` instead of silently falling back to JSON - [ ] BDD tests cover both `rich` and `color` format paths in `format_output()` - [ ] A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional details - [ ] The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly - [ ] The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done - [ ] All nox stages pass - [ ] Coverage >= 97% --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo added a new dependency

2026-04-06 08:26:19 +00:00

#936 Epic: Output Rendering Pipeline Integration — Wire Commands to OutputSession Framework

freemo referenced this issue

2026-04-06 08:29:44 +00:00

[Automated] CleverAgents Build Session - 2026-04-06 #3775

freemo added the

Points

label

2026-04-06 08:31:46 +00:00

freemo referenced this issue

2026-04-06 08:33:59 +00:00