Skip to content

fix: 🐛 Improve command help and option diagnostics - #82

Merged
oxspan merged 1 commit into
developfrom
feature/65
Nov 12, 2026
Merged

oxspan merged 1 commit into
developfrom
feature/65

Conversation

@oxspan

@oxspan oxspan commented Nov 12, 2026

Copy link
Copy Markdown
Owner

Problem

Redirected help could contain ANSI escapes, every command shared one large option list, and argument errors omitted the option a user needed to correct.

Refs #65

Changes

  • Disable help colors when the JVM has no terminal console or NO_COLOR is present, including an empty value. This overrides forced Picocli colors for redirected output.
  • Show required and accepted options, combination notes and an example for each command. Root and command-family help list commands; inspect --help also exposes its offline subcommands.
  • Reuse command-guide option sets for the strict combinations already validated by the interpreter. Execution parsing and existing general-command validation remain intact.
  • Name unknown options and invalid/missing option values in JSON errors. Strip attached values and avoid echoing parser exception messages. Preserve error schemas, codes and exit statuses.
  • Add command-help examples to both quickstarts and describe output behavior in the CLI contract. No CLI flags or dependencies are added.

Validation

  • Full Linux tests, coverage and release-input checks passed: XML reports 249 tests, zero failures/errors/skips; one entry represents an empty Windows-only specification. Line coverage 95.35%, branch coverage 80.45%, against unchanged 90%/80% floors.
  • Native Windows JDK 21: all 15 CLI usability regressions passed, including real ConPTY output and an empty NO_COLOR value.
  • Packaged CLI: 52 Linux scenarios covering all 21 command help pages, command families, redirected and terminal output, safe diagnostics, version output and the command launcher. Native Windows batch launcher also passed redirected command-specific help checks without ANSI or stderr.
  • The exact final test classes fail 13 cases against the prior JAR; the two passing controls verify permitted colored terminal output and safe positional-error fallback.

Examples and message wording remain human-readable help, not a machine-readable API. Scripts should continue to use versioned JSON envelopes and error codes for command execution.

@github-actions

Copy link
Copy Markdown
Contributor

Linux CI: success · Commit 3104251

Test results (Linux)

Total Passed Failed Errors Skipped
249 249 0 0 0

Test coverage

Metric Covered / total Coverage Minimum Result
LINE 2193 / 2300 95.35% 90.00% PASS
BRANCH 1288 / 1601 80.45% 80.00% PASS

Includes the test JVM and CLI subprocesses. Excludes optional real-Collector smoke tests.

Workflow logs and report artifacts

Updated on each CI run. Windows checks, when required, are reported separately in the workflow.

@oxspan
oxspan merged commit 22c81fa into develop Nov 12, 2026
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant