[PR #1141] [CLOSED] fix(cli): show usage for rea mcp doctor --help #2677

New issue

Closed

opened 2026-10-17 21:08:57 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-17 21:08:57 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/1141
Author: @aniruddhaadak80
Created: 10/8/2026
Status: ❌ Closed

Base: main ← Head: fix/cli-mcp-doctor-help

📝 Commits (1)

5e0e40f fix(cli): show usage for rea mcp doctor --help

📊 Changes

2 files changed (+116 additions, -6 deletions)

View changed files

📝 src/mcpDoctor.ts (+41 -6)
➕ tests/boundary/cli/mcpDoctorHelpCli.test.ts (+75 -0)

📄 Description

Summary

rea mcp doctor --help exits 1 instead of showing usage. rea mcp --help advertises the --help option and docs/cli.md directs callers to a command's --help for its arguments and output options, so a documented command-discovery request fails today.

Fixes #1127

Problem and expected behavior

scripts/rea.mjs routes rea mcp doctor straight to the production dispatcher entry (runProductionMcpDoctorCli) before Incur sees the request, so Incur's shared --help handling never runs. The dispatcher's own option parser knows only the output options, so --help is classified as an unknown option:

$ rea mcp doctor --help
code: VALIDATION_ERROR
message: "Unknown mcp doctor option: --help"
# exit code 1

Smallest trigger: run rea mcp doctor --help against any checkout with dist/ built. Violated invariant: an option the command's own help advertises is answered with a validation failure rather than usage.

Expected: the help request renders the command's usage and exits 0 without starting a diagnostic session, and a genuinely unknown option keeps its actionable validation error.

Change and scope

Recognize --help and -h in the dispatcher's argument parser and return a help result before the diagnostic session is started, so no server process is spawned for a help request.
Render usage with Incur's Help.formatCommand so the header, kebab-cased flags and option columns match rea doctor --help and the rest of the CLI.
Declare the output options the dispatcher actually accepts in one schema used to render that help, and keep the parser's existing validation and error messages for an unknown or invalid option.

Intentionally not included: no change to Incur's mcp routing, to the parent rea mcp help, to the diagnostic workflow itself, or to any provider behavior. scripts/rea.mjs already routes this request here, so the dispatcher entry is the correct seam — the request must be answered before a session starts, and it must describe the options this entry really accepts rather than Incur's generic built-in description.

Contract and boundary impact

Semantic owner and earliest changed stage: CLI argument parsing in src/mcpDoctor.ts; the failure was request parsing and validation.
CLI and MCP/tool-catalog contract: CLI only. rea mcp doctor --help moves from exit 1 VALIDATION_ERROR to exit 0 usage text. --json, --format <fmt>, --format=<fmt> and --full-output are unchanged, and an unknown or invalid option still exits 1 with the same messages. No MCP tool, prompt, contract, or catalog entry changes.
Provider, bridge, target-format, or platform compatibility: not applicable; no provider, bridge or target-format code is reached by a help request.
Evidence, artifact, provenance, or reconstruction contract: not applicable; no evidence, artifact or provenance output is produced or changed.
Process execution, authorization, cleanup, or containment impact: reduced. The help path returns before runProductionMcpDoctor, so no stdio child process is spawned and there is nothing to clean up.
Generated metadata (docs/public/product-catalog.json), package, or installation impact: none. No contract, catalog, or skill content changed.

Evidence and regression coverage

Tests added or updated: tests/boundary/cli/mcpDoctorHelpCli.test.ts, three compiled-CLI boundary cases covering both help flags, help combined with output options (including an invalid --format), and the retained validation errors.
Base reproduction or other evidence: on the base revision the two help cases fail with expected { exitCode: 1, ... } to match object { exitCode: 0 } while the retained-error case already passes. After the fix all three pass. npm run verify:test-discovery reports all 635 test files discovered exactly once.
User-visible CLI/MCP output:

$ rea mcp doctor --help
rea mcp doctor — Validate MCP server startup and tool listing

Usage: rea mcp doctor [options]

Options:
  --format <toon|json|yaml|md|jsonl>  Output format
  --json                              Emit the report as JSON
  --full-output                       Show the full output envelope
# exit code 0, no stderr output

$ rea mcp doctor --bogus
code: VALIDATION_ERROR
message: "Unknown mcp doctor option: --bogus"
# exit code 1, unchanged

Remaining proof gaps: none for this change. Help output is asserted exactly, so an accepted option added without updating the rendered usage fails the boundary case.

Validation performed

npm run check:fast — typecheck and lint passed
npm run check — typecheck, lint, knip and metadata:check passed
npm run docs:check — passed, generated documents unchanged
npm run verify:test-discovery — passed
npm run jscpd and npm run scan:todos — passed
npx vitest run --coverage.enabled=false tests/boundary/mcp/mcpDoctor.test.ts tests/boundary/cli/mcpDoctorHelpCli.test.ts tests/boundary/cli/dispatcher.test.ts tests/boundary/cli/cliOutput.test.ts — 18 tests passed
node scripts/rea.mjs mcp doctor --json — exit 0, healthy: true, 138 of 138 tools and 6 of 6 prompts matched, confirming the diagnostic session itself is unaffected

Note on local formatting: npm run format:check reports ~2069 files, all of them pre-existing, because this checkout was created with core.autocrlf=true (CRLF on disk). Both files in this change were verified clean with oxfmt after normalizing to LF, and Git normalizes to LF on commit, so CI sees the committed LF content.

Compatibility, safety, and release

Breaking changes or migration steps: none. The change only converts a failing help request into the advertised behavior.
Real Hopper/Ghidra, browser, or OS coverage: not applicable. No provider, bridge, browser or platform behavior is touched, and no real-provider verification is claimed.
Package or release metadata impact: none.
Security, privacy, process, or containment review: the change removes a child-process spawn for one request. No credentials, environment values or target inputs are printed; the help text is static.

Review checklist

The PR has one focused outcome and the title follows type(scope): outcome.
Related issue is linked, or the reason for not linking one is stated above.
Tests cover changed observable behavior and meaningful failure paths.
Owning docs, contracts, and generated metadata are updated where needed.
User-visible CLI/MCP changes include representative output.
I checked the final diff for secrets, unrelated cleanup, and unsupported claims.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/morluto/rea/pull/1141 **Author:** [@aniruddhaadak80](https://github.com/aniruddhaadak80) **Created:** 10/8/2026 **Status:** ❌ Closed **Base:** `main` ← **Head:** `fix/cli-mcp-doctor-help` --- ### 📝 Commits (1) - [`5e0e40f`](https://github.com/morluto/rea/commit/5e0e40f196c79cdde6709f82fd6ce91952d2f3df) fix(cli): show usage for rea mcp doctor --help ### 📊 Changes **2 files changed** (+116 additions, -6 deletions) <details> <summary>View changed files</summary> 📝 `src/mcpDoctor.ts` (+41 -6) ➕ `tests/boundary/cli/mcpDoctorHelpCli.test.ts` (+75 -0) </details> ### 📄 Description ## Summary `rea mcp doctor --help` exits 1 instead of showing usage. `rea mcp --help` advertises the `--help` option and `docs/cli.md` directs callers to a command's `--help` for its arguments and output options, so a documented command-discovery request fails today. Fixes #1127 ## Problem and expected behavior `scripts/rea.mjs` routes `rea mcp doctor` straight to the production dispatcher entry (`runProductionMcpDoctorCli`) before Incur sees the request, so Incur's shared `--help` handling never runs. The dispatcher's own option parser knows only the output options, so `--help` is classified as an unknown option: ```text $ rea mcp doctor --help code: VALIDATION_ERROR message: "Unknown mcp doctor option: --help" # exit code 1 ``` Smallest trigger: run `rea mcp doctor --help` against any checkout with `dist/` built. Violated invariant: an option the command's own help advertises is answered with a validation failure rather than usage. Expected: the help request renders the command's usage and exits 0 without starting a diagnostic session, and a genuinely unknown option keeps its actionable validation error. ## Change and scope - Recognize `--help` and `-h` in the dispatcher's argument parser and return a help result before the diagnostic session is started, so no server process is spawned for a help request. - Render usage with Incur's `Help.formatCommand` so the header, kebab-cased flags and option columns match `rea doctor --help` and the rest of the CLI. - Declare the output options the dispatcher actually accepts in one schema used to render that help, and keep the parser's existing validation and error messages for an unknown or invalid option. Intentionally not included: no change to Incur's `mcp` routing, to the parent `rea mcp` help, to the diagnostic workflow itself, or to any provider behavior. `scripts/rea.mjs` already routes this request here, so the dispatcher entry is the correct seam — the request must be answered before a session starts, and it must describe the options this entry really accepts rather than Incur's generic built-in description. ## Contract and boundary impact - Semantic owner and earliest changed stage: CLI argument parsing in `src/mcpDoctor.ts`; the failure was request parsing and validation. - CLI and MCP/tool-catalog contract: CLI only. `rea mcp doctor --help` moves from exit 1 `VALIDATION_ERROR` to exit 0 usage text. `--json`, `--format <fmt>`, `--format=<fmt>` and `--full-output` are unchanged, and an unknown or invalid option still exits 1 with the same messages. No MCP tool, prompt, contract, or catalog entry changes. - Provider, bridge, target-format, or platform compatibility: not applicable; no provider, bridge or target-format code is reached by a help request. - Evidence, artifact, provenance, or reconstruction contract: not applicable; no evidence, artifact or provenance output is produced or changed. - Process execution, authorization, cleanup, or containment impact: reduced. The help path returns before `runProductionMcpDoctor`, so no stdio child process is spawned and there is nothing to clean up. - Generated metadata (`docs/public/product-catalog.json`), package, or installation impact: none. No contract, catalog, or skill content changed. ## Evidence and regression coverage - Tests added or updated: `tests/boundary/cli/mcpDoctorHelpCli.test.ts`, three compiled-CLI boundary cases covering both help flags, help combined with output options (including an invalid `--format`), and the retained validation errors. - Base reproduction or other evidence: on the base revision the two help cases fail with `expected { exitCode: 1, ... } to match object { exitCode: 0 }` while the retained-error case already passes. After the fix all three pass. `npm run verify:test-discovery` reports all 635 test files discovered exactly once. - User-visible CLI/MCP output: ```text $ rea mcp doctor --help rea mcp doctor — Validate MCP server startup and tool listing Usage: rea mcp doctor [options] Options: --format <toon|json|yaml|md|jsonl> Output format --json Emit the report as JSON --full-output Show the full output envelope # exit code 0, no stderr output $ rea mcp doctor --bogus code: VALIDATION_ERROR message: "Unknown mcp doctor option: --bogus" # exit code 1, unchanged ``` - Remaining proof gaps: none for this change. Help output is asserted exactly, so an accepted option added without updating the rendered usage fails the boundary case. ## Validation performed - `npm run check:fast` — typecheck and lint passed - `npm run check` — typecheck, lint, knip and metadata:check passed - `npm run docs:check` — passed, generated documents unchanged - `npm run verify:test-discovery` — passed - `npm run jscpd` and `npm run scan:todos` — passed - `npx vitest run --coverage.enabled=false tests/boundary/mcp/mcpDoctor.test.ts tests/boundary/cli/mcpDoctorHelpCli.test.ts tests/boundary/cli/dispatcher.test.ts tests/boundary/cli/cliOutput.test.ts` — 18 tests passed - `node scripts/rea.mjs mcp doctor --json` — exit 0, `healthy: true`, 138 of 138 tools and 6 of 6 prompts matched, confirming the diagnostic session itself is unaffected Note on local formatting: `npm run format:check` reports ~2069 files, all of them pre-existing, because this checkout was created with `core.autocrlf=true` (CRLF on disk). Both files in this change were verified clean with oxfmt after normalizing to LF, and Git normalizes to LF on commit, so CI sees the committed LF content. ## Compatibility, safety, and release - Breaking changes or migration steps: none. The change only converts a failing help request into the advertised behavior. - Real Hopper/Ghidra, browser, or OS coverage: not applicable. No provider, bridge, browser or platform behavior is touched, and no real-provider verification is claimed. - Package or release metadata impact: none. - Security, privacy, process, or containment review: the change removes a child-process spawn for one request. No credentials, environment values or target inputs are printed; the help text is static. ## Review checklist - [x] The PR has one focused outcome and the title follows `type(scope): outcome`. - [x] Related issue is linked, or the reason for not linking one is stated above. - [x] Tests cover changed observable behavior and meaningful failure paths. - [x] Owning docs, contracts, and generated metadata are updated where needed. - [x] User-visible CLI/MCP changes include representative output. - [x] I checked the final diff for secrets, unrelated cleanup, and unsupported claims. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-17 21:08:57 +00:00