feat(cli): add output rendering framework with materialization strategies #311

Closed
opened 2026-02-22 23:41:10 +00:00 by freemo · 0 comments
Owner

Metadata

  • Commit: feat(cli): add output rendering framework with materialization strategies
  • Branch: feature/m4-output-rendering

Subtasks

  • Implement OutputSession context manager that tracks active element handles and manages concurrent producer output without interleaving.
  • Implement ElementHandle base class with subclasses: PanelHandle (titled content blocks), TableHandle (structured rows/columns), StatusHandle (single-line status updates), and ProgressHandle (progress bars with label/tick/indeterminate modes).
  • Implement ProgressHandle API: set_progress(fraction), set_label(text), tick(), and indeterminate() mode. Throttle updates in rich mode (max 10 FPS); omit in JSON mode.
  • Implement 6 materialization strategies: RichMaterializer (in-place terminal updates via Rich), ColorMaterializer (ANSI codes without cursor movement), TableMaterializer (tabulate-style), PlainMaterializer (sequential buffer-flush, ASCII-only), JsonMaterializer (accumulate-then-serialize), YamlMaterializer (accumulate-then-dump).
  • Add materializer selection from --format flag with automatic fallback (Rich → Color → Plain when terminal capabilities are insufficient).
  • Port existing format_output() helper and command-level formatting to produce output through OutputSession handles instead of direct console.print().
  • Add unified error envelope for JSON/YAML materializers: {"error": {"code": "...", "message": "...", "details": {...}}}.
  • Add docs/reference/output_rendering.md documenting the OutputSession/ElementHandle architecture, materializer selection, and producer integration guide.
  • Tests (Behave): Add features/output_rendering.feature with scenarios for each materializer, progress handle updates, concurrent producers, and format fallback.
  • Tests (Robot): Add robot/output_rendering.robot for end-to-end output format verification across commands.
  • Tests (ASV): Add benchmarks/output_rendering_bench.py for materializer throughput and progress handle overhead.
  • Verify coverage >=97% via nox -s coverage_report. If coverage is <97% then review the current unit test coverage report at build/coverage.xml and use it to write new Behave based unit tests to improve code coverage. Specifically, write Behave style unit tests that are descriptively named and specifically improves coverage on whichever file has the most uncovered lines by writing tests that will target the uncovered lines in the report. Once that is done rerun nox -s coverage_report to verify all tests pass and coverage is above >=97%. Only mark this as complete once coverage is >=97%, if not repeat this task as many times as is needed until coverage reaches >=97%.
  • Run nox (all default sessions, including benchmark), fix any errors if needed ensuring nox passes across entire code base, do not ignore any failure even if it seems unrelated to this commit, fix it.

Section: ### Section 8: Large Project Autonomy & Context [M6]
Status: Completed

## Metadata - **Commit**: `feat(cli): add output rendering framework with materialization strategies` - **Branch**: `feature/m4-output-rendering` ## Subtasks - [x] Implement `OutputSession` context manager that tracks active element handles and manages concurrent producer output without interleaving. - [x] Implement `ElementHandle` base class with subclasses: `PanelHandle` (titled content blocks), `TableHandle` (structured rows/columns), `StatusHandle` (single-line status updates), and `ProgressHandle` (progress bars with label/tick/indeterminate modes). - [x] Implement `ProgressHandle` API: `set_progress(fraction)`, `set_label(text)`, `tick()`, and `indeterminate()` mode. Throttle updates in rich mode (max 10 FPS); omit in JSON mode. - [x] Implement 6 materialization strategies: `RichMaterializer` (in-place terminal updates via Rich), `ColorMaterializer` (ANSI codes without cursor movement), `TableMaterializer` (tabulate-style), `PlainMaterializer` (sequential buffer-flush, ASCII-only), `JsonMaterializer` (accumulate-then-serialize), `YamlMaterializer` (accumulate-then-dump). - [x] Add materializer selection from `--format` flag with automatic fallback (Rich → Color → Plain when terminal capabilities are insufficient). - [x] Port existing `format_output()` helper and command-level formatting to produce output through `OutputSession` handles instead of direct `console.print()`. - [x] Add unified error envelope for JSON/YAML materializers: `{"error": {"code": "...", "message": "...", "details": {...}}}`. - [x] Add `docs/reference/output_rendering.md` documenting the OutputSession/ElementHandle architecture, materializer selection, and producer integration guide. - [x] Tests (Behave): Add `features/output_rendering.feature` with scenarios for each materializer, progress handle updates, concurrent producers, and format fallback. - [x] Tests (Robot): Add `robot/output_rendering.robot` for end-to-end output format verification across commands. - [x] Tests (ASV): Add `benchmarks/output_rendering_bench.py` for materializer throughput and progress handle overhead. - [x] Verify coverage >=97% via `nox -s coverage_report`. If coverage is <97% then review the current unit test coverage report at `build/coverage.xml` and use it to write new Behave based unit tests to improve code coverage. Specifically, write Behave style unit tests that are descriptively named and specifically improves coverage on whichever file has the most uncovered lines by writing tests that will target the uncovered lines in the report. Once that is done rerun `nox -s coverage_report` to verify all tests pass and coverage is above >=97%. Only mark this as complete once coverage is >=97%, if not repeat this task as many times as is needed until coverage reaches >=97%. - [x] Run `nox` (all default sessions, including benchmark), fix any errors if needed ensuring nox passes across **entire** code base, do not ignore any failure even if it seems unrelated to this commit, fix it. **Section**: ### Section 8: Large Project Autonomy & Context [M6] **Status**: Completed
freemo added this to the v3.5.0 milestone 2026-02-22 23:41:10 +00:00
freemo self-assigned this 2026-02-22 23:41:10 +00:00
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Reference
cleveragents/cleveragents-core#311
No description provided.