cleveragents/cleveragents-core

Fork 3

UAT: `--format` help text on `version`, `info`, and `diagnostics` commands omits `table` and `color` formats — spec defines 6 valid formats #2128

New issue

Open

opened 2026-04-03 04:18:07 +00:00 by freemo · 1 comment

freemo commented

2026-04-03 04:18:07 +00:00

Owner

Metadata

Branch: fix/cli-format-help-text-missing-formats
Commit Message: fix(cli): use FORMAT_HELP constant for --format option in version, info, diagnostics commands
Milestone: v3.7.0
Parent Epic: #936

Background and Context

The project specification (§Global Options) defines 6 valid output formats for the --format option:

--format rich|color|table|plain|json|yaml

The VALID_FORMATS constant in src/cleveragents/cli/constants.py correctly captures all 6 formats:

VALID_FORMATS: tuple[str, ...] = ("json", "yaml", "plain", "table", "rich", "color")

A FORMAT_HELP constant also exists in constants.py with the correct full description. However, the version, info, and diagnostics CLI commands bypass this constant and use inline help strings that only list 4 of the 6 formats, omitting table and color.

Current Behavior

Running agents version --help, agents info --help, or agents diagnostics --help shows:

--format TEXT  Output format: rich, plain, json, yaml

The table and color formats are silently omitted from the help text, even though they are fully functional when specified.

In src/cleveragents/cli/main.py, all three commands define their --format option with the same incomplete inline help string:

@app.command()
def version(
    fmt: str = typer.Option(
        "rich",
        "--format",
        "-f",
        help="Output format: rich, plain, json, yaml",  # Missing: color, table
    ),
) -> None:
    ...

@app.command()
def info(
    fmt: str = typer.Option(
        "rich",
        "--format",
        "-f",
        help="Output format: rich, plain, json, yaml",  # Missing: color, table
    ),
) -> None:
    ...

@app.command()
def diagnostics(
    ...
    fmt: str = typer.Option(
        "rich",
        "--format",
        "-f",
        help="Output format: rich, plain, json, yaml",  # Missing: color, table
    ),
) -> None:
    ...

Expected Behavior

All three commands should display the full list of 6 valid formats in their --format help text, consistent with the spec and the FORMAT_HELP constant already defined in constants.py:

--format TEXT  Output format: json, yaml, plain, table, rich, or color (default: rich)

The fix is to replace the inline help="Output format: rich, plain, json, yaml" strings with a reference to FORMAT_HELP from src/cleveragents/cli/constants.py.

Steps to Reproduce

agents version --help
# Shows: --format TEXT  Output format: rich, plain, json, yaml
# Expected: --format TEXT  Output format: json, yaml, plain, table, rich, or color (default: rich)

agents info --help
# Same issue

agents diagnostics --help
# Same issue

Acceptance Criteria

agents version --help displays all 6 valid formats (json, yaml, plain, table, rich, color) in the --format option help text
agents info --help displays all 6 valid formats in the --format option help text
agents diagnostics --help displays all 6 valid formats in the --format option help text
The --format help text in all three commands is sourced from the FORMAT_HELP constant in src/cleveragents/cli/constants.py (no more inline strings)
No regression: all 6 formats continue to work correctly when passed to each command

Supporting Information

Affected file: src/cleveragents/cli/main.py — version(), info(), and diagnostics() command definitions
Fix source: FORMAT_HELP constant in src/cleveragents/cli/constants.py (already correct)
Severity: Low — the table and color formats DO work when specified (they are accepted by format_output()), but users reading the help text would not know these formats are available
Discovered during: UAT testing of the output rendering pipeline

Subtasks

Replace inline help="Output format: rich, plain, json, yaml" in version() with help=FORMAT_HELP (importing FORMAT_HELP from constants.py)
Replace inline help="Output format: rich, plain, json, yaml" in info() with help=FORMAT_HELP
Replace inline help="Output format: rich, plain, json, yaml" in diagnostics() with help=FORMAT_HELP
Verify FORMAT_HELP is imported at the top of main.py (add import if missing)
Tests (Behave): Add/update scenarios verifying --help output for version, info, and diagnostics includes all 6 format names
Verify coverage >= 97% via nox -s coverage_report
Run nox (all default sessions), fix any errors

Definition of Done

This issue is complete when:

All subtasks above are completed and checked off.
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly (fix(cli): use FORMAT_HELP constant for --format option in version, info, diagnostics commands), followed by a blank line, then additional lines providing relevant details about the implementation.
The commit is pushed to the remote on the branch matching the Branch in Metadata exactly (fix/cli-format-help-text-missing-formats).
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-help-text-missing-formats` - **Commit Message**: `fix(cli): use FORMAT_HELP constant for --format option in version, info, diagnostics commands` - **Milestone**: v3.7.0 - **Parent Epic**: #936 ## Background and Context The project specification (§Global Options) defines 6 valid output formats for the `--format` option: > `--format rich|color|table|plain|json|yaml` The `VALID_FORMATS` constant in `src/cleveragents/cli/constants.py` correctly captures all 6 formats: ```python VALID_FORMATS: tuple[str, ...] = ("json", "yaml", "plain", "table", "rich", "color") ``` A `FORMAT_HELP` constant also exists in `constants.py` with the correct full description. However, the `version`, `info`, and `diagnostics` CLI commands bypass this constant and use inline help strings that only list 4 of the 6 formats, omitting `table` and `color`. ## Current Behavior Running `agents version --help`, `agents info --help`, or `agents diagnostics --help` shows: ``` --format TEXT Output format: rich, plain, json, yaml ``` The `table` and `color` formats are silently omitted from the help text, even though they are fully functional when specified. In `src/cleveragents/cli/main.py`, all three commands define their `--format` option with the same incomplete inline help string: ```python @app.command() def version( fmt: str = typer.Option( "rich", "--format", "-f", help="Output format: rich, plain, json, yaml", # Missing: color, table ), ) -> None: ... @app.command() def info( fmt: str = typer.Option( "rich", "--format", "-f", help="Output format: rich, plain, json, yaml", # Missing: color, table ), ) -> None: ... @app.command() def diagnostics( ... fmt: str = typer.Option( "rich", "--format", "-f", help="Output format: rich, plain, json, yaml", # Missing: color, table ), ) -> None: ... ``` ## Expected Behavior All three commands should display the full list of 6 valid formats in their `--format` help text, consistent with the spec and the `FORMAT_HELP` constant already defined in `constants.py`: ``` --format TEXT Output format: json, yaml, plain, table, rich, or color (default: rich) ``` The fix is to replace the inline `help="Output format: rich, plain, json, yaml"` strings with a reference to `FORMAT_HELP` from `src/cleveragents/cli/constants.py`. ## Steps to Reproduce ```bash agents version --help # Shows: --format TEXT Output format: rich, plain, json, yaml # Expected: --format TEXT Output format: json, yaml, plain, table, rich, or color (default: rich) agents info --help # Same issue agents diagnostics --help # Same issue ``` ## Acceptance Criteria - [ ] `agents version --help` displays all 6 valid formats (`json`, `yaml`, `plain`, `table`, `rich`, `color`) in the `--format` option help text - [ ] `agents info --help` displays all 6 valid formats in the `--format` option help text - [ ] `agents diagnostics --help` displays all 6 valid formats in the `--format` option help text - [ ] The `--format` help text in all three commands is sourced from the `FORMAT_HELP` constant in `src/cleveragents/cli/constants.py` (no more inline strings) - [ ] No regression: all 6 formats continue to work correctly when passed to each command ## Supporting Information - **Affected file**: `src/cleveragents/cli/main.py` — `version()`, `info()`, and `diagnostics()` command definitions - **Fix source**: `FORMAT_HELP` constant in `src/cleveragents/cli/constants.py` (already correct) - **Severity**: Low — the `table` and `color` formats DO work when specified (they are accepted by `format_output()`), but users reading the help text would not know these formats are available - **Discovered during**: UAT testing of the output rendering pipeline ## Subtasks - [ ] Replace inline `help="Output format: rich, plain, json, yaml"` in `version()` with `help=FORMAT_HELP` (importing `FORMAT_HELP` from `constants.py`) - [ ] Replace inline `help="Output format: rich, plain, json, yaml"` in `info()` with `help=FORMAT_HELP` - [ ] Replace inline `help="Output format: rich, plain, json, yaml"` in `diagnostics()` with `help=FORMAT_HELP` - [ ] Verify `FORMAT_HELP` is imported at the top of `main.py` (add import if missing) - [ ] Tests (Behave): Add/update scenarios verifying `--help` output for `version`, `info`, and `diagnostics` includes all 6 format names - [ ] Verify coverage >= 97% via `nox -s coverage_report` - [ ] Run `nox` (all default sessions), fix any errors ## Definition of Done This issue is complete when: - [ ] All subtasks above are completed and checked off. - [ ] A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly (`fix(cli): use FORMAT_HELP constant for --format option in version, info, diagnostics commands`), followed by a blank line, then additional lines providing relevant details about the implementation. - [ ] The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly (`fix/cli-format-help-text-missing-formats`). - [ ] 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 this to the v3.7.0 milestone

2026-04-03 04:18:12 +00:00

freemo added a new dependency

2026-04-03 04:18:42 +00:00

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

freemo referenced this issue

2026-04-03 04:20:11 +00:00

[CA-AUTO] UAT Pool Supervisor — v3.7.0 — Session Tracker #2023

freemo referenced this issue

2026-04-03 04:21:38 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 721 — v3.7.0 #2138

freemo referenced this issue

2026-04-03 04:21:53 +00:00

[CA-AUTO] UAT Pool Supervisor — v3.7.0 — Session Tracker #2023

freemo self-assigned this

2026-04-03 16:58:03 +00:00

freemo added the

MoSCoW

Could have

label

2026-04-03 18:28:05 +00:00

freemo commented

2026-04-03 18:28:16 +00:00

Author

Owner

MoSCoW classification: Could Have

Rationale: This is a low-priority or backlog item. Desirable but not necessary for the milestone. Include only if time permits.

Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: ca-project-owner

MoSCoW classification: **Could Have** Rationale: This is a low-priority or backlog item. Desirable but not necessary for the milestone. Include only if time permits. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner