cleveragents/cleveragents-core
4
0
Fork 3
Code Issues 6.0k Pull Requests 115 Actions Packages Projects Releases Wiki Activity

feat(cli): final CLI polish and UX consistency pass (#1018)
CI / build (push) Successful in 19s
Details
CI / lint (push) Successful in 3m21s
Details
CI / quality (push) Successful in 3m43s
Details
CI / typecheck (push) Successful in 4m13s
Details
CI / benchmark-regression (push) Has been skipped
Details
CI / security (push) Successful in 4m17s
Details
CI / unit_tests (push) Successful in 5m45s
Details
CI / docker (push) Successful in 1m3s
Details
CI / integration_tests (push) Successful in 6m49s
Details
CI / e2e_tests (push) Successful in 9m8s
Details
CI / coverage (push) Failing after 13m47s
Details
CI / benchmark-publish (push) Successful in 19m43s
Details
CI / status-check (push) Failing after 1s
Details

Browse Source 
## Summary

Final CLI polish and UX consistency pass: shared constants, centralized error formatting, shell completion, and standardized help text.

### New Modules

- **`cli/constants.py`** (70 lines): Exit codes (`EXIT_SUCCESS`=0 through `EXIT_CONFLICT`=4), format defaults (`FORMAT_TEXT`, `FORMAT_JSON`, `FORMAT_TABLE`)
- **`cli/errors.py`** (105 lines): `cli_error()` with hint support, `cli_warning()`, `cli_not_found()` with resource-type-aware hint

### CLI Changes

- Shell `completion` command generating scripts for bash/zsh/fish/powershell
- Standardized help text across command modules
- Error functions exported from `cli/__init__.py`

### Tests

- **17 Behave scenarios**: Exit codes, error formatting, cli_not_found, format constants, help text, completion
- **15 Robot integration tests**: All subcommands respond to --help, invalid commands return non-zero, completion generation works

### Quality Gates

| Session | Result |
|---|---|
| `nox -s lint` | PASS |
| `nox -s typecheck` | PASS (0 errors) |
| `nox -s unit_tests` | PASS (10,912 scenarios) |
| `nox -s coverage_report` | 97% (>= 97%) |

Closes #861

Reviewed-on: #1018
Co-authored-by: Brent E. Edwards <brent.edwards@cleverthis.com>
Co-committed-by: Brent E. Edwards <brent.edwards@cleverthis.com>
This commit was merged in pull request #1018.
This commit is contained in:
Brent Edwards
2026-03-21 01:14:18 +00:00
committed by Forgejo
parent 00897be24a
commit 95d3e09925
10 changed files with 1011 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
features/cli_consistency.feature
+136
View File
@@ -0,0 +1,136 @@
Feature: CLI consistency and UX polish
As a developer
I want all CLI commands to follow consistent UX patterns
So that the tool is predictable and easy to use
# -----------------------------------------------------------------
# Exit code constants
# -----------------------------------------------------------------
Scenario: Exit code constants are defined
Given the CLI constants module is imported
Then EXIT_SUCCESS should equal 0
And EXIT_ERROR should equal 1
And EXIT_USAGE should equal 2
And EXIT_NOT_FOUND should equal 3
And EXIT_CONFLICT should equal 4
# -----------------------------------------------------------------
# Error formatting
# -----------------------------------------------------------------
Scenario: cli_error displays standardized error and exits
Given the CLI errors module is imported
When I call cli_error with only message "something broke"
Then the process should exit with code 1
And the stderr output should contain "Error:"
And the stderr output should contain "something broke"
Scenario: cli_error displays hint when provided
Given the CLI errors module is imported
When I call cli_error with message "not found" and hint "check the name"
Then the process should exit with code 1
And the stderr output should contain "Hint: check the name"
Scenario: cli_error uses custom exit code
Given the CLI errors module is imported
When I call cli_error with message "bad usage" and exit code 2
Then the process should exit with code 2
Scenario: cli_warning displays warning without exiting
Given the CLI errors module is imported
When I call cli_warning with only message "heads up"
Then the stderr output should contain "Warning:"
And the stderr output should contain "heads up"
Scenario: cli_warning displays hint when provided
Given the CLI errors module is imported
When I call cli_warning with message "slow" and hint "use cache"
Then the stderr output should contain "Hint: use cache"
Scenario: cli_not_found formats correctly and exits with code 3
Given the CLI errors module is imported
When I call cli_not_found with type "Project" and name "missing-proj"
Then the process should exit with code 3
And the stderr output should contain "Project 'missing-proj' not found"
And the stderr output should contain "Hint:"
# -----------------------------------------------------------------
# Format constants
# -----------------------------------------------------------------
Scenario: Format constants are consistent
Given the CLI constants module is imported
Then FORMAT_HELP should mention "json"
And FORMAT_HELP should mention "yaml"
And FORMAT_HELP should mention "plain"
And DEFAULT_FORMAT should equal "rich"
And VALID_FORMATS should contain "json"
And VALID_FORMATS should contain "yaml"
And VALID_FORMATS should contain "plain"
And VALID_FORMATS should contain "table"
And VALID_FORMATS should contain "rich"
Scenario: Named format shortcut constants are defined
Given the CLI constants module is imported
Then FORMAT_TEXT should equal "plain"
And FORMAT_JSON should equal "json"
And FORMAT_TABLE should equal "table"
# -----------------------------------------------------------------
# Help text consistency
# -----------------------------------------------------------------
Scenario: Main CLI provides help output
Given a CLI consistency test runner
When I invoke the CLI with "--help"
Then the invoked CLI exit code should be 0
And the invoked CLI output should contain "AI-powered development assistant"
Scenario: Version command provides output
Given a CLI consistency test runner
When I invoke the CLI with "--version"
Then the invoked CLI exit code should be 0
And the invoked CLI output should contain "CleverAgents"
Scenario: Invalid command returns usage exit code
Given a CLI consistency test runner
When I invoke the CLI with "nonexistent-command-xyz"
Then the invoked CLI exit code should be 2
# -----------------------------------------------------------------
# Shell completion command
# -----------------------------------------------------------------
Scenario: Completion command exists
Given a CLI consistency test runner
When I invoke the CLI with "completion --help"
Then the invoked CLI exit code should be 0
And the invoked CLI output should contain "completion"
Scenario: Completion rejects unsupported shell
Given a CLI consistency test runner
When I invoke the CLI with "completion ksh"
Then the invoked CLI exit code should be 2
# -----------------------------------------------------------------
# JSON/text format switching
# -----------------------------------------------------------------
Scenario: Version command supports JSON format
Given a CLI consistency test runner
When I invoke the CLI with "version --format json"
Then the invoked CLI exit code should be 0
And the invoked CLI output should be valid JSON
Scenario: Version command supports YAML format
Given a CLI consistency test runner
When I invoke the CLI with "version --format yaml"
Then the invoked CLI exit code should be 0
And the invoked CLI output should contain "version:"
Scenario: Version command supports plain format
Given a CLI consistency test runner
When I invoke the CLI with "version --format plain"
Then the invoked CLI exit code should be 0
And the invoked CLI output should contain "version:"