morluto/rea

Fork 0

mirror of https://github.com/morluto/rea.git synced 2026-11-05 06:45:22 +00:00

[PR #6489] [MERGED] fix(doctor): report a missing --format value as MISSING_OUTPUT_VALUE #7367

New issue

Closed

opened 2026-11-01 21:47:21 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-11-01 21:47:21 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/6489
Author: @ezrabrilliant
Created: 10/23/2026
Status: ✅ Merged
Merged: 10/23/2026
Merged by: @morluto

Base: main ← Head: fix/mcp-doctor-missing-format

📝 Commits (1)

0cac844 fix(doctor): report a missing --format value as MISSING_OUTPUT_VALUE

📊 Changes

3 files changed (+49 additions, -3 deletions)

View changed files

📝 src/cliOutput.ts (+5 -1)
📝 src/mcpDoctor.ts (+14 -2)
📝 tests/boundary/cli/mcpDoctorHelpCli.test.ts (+30 -0)

📄 Description

Summary

Fixes #6455.

rea mcp doctor --format and rea mcp doctor --format= returned VALIDATION_ERROR with Invalid output format: missing. docs/cli.md documents MISSING_OUTPUT_VALUE for a valued output flag given without a value, and capabilities already returns that code. mcp doctor now returns MISSING_OUTPUT_VALUE with the same message capabilities uses. A format value that is present but unsupported still returns VALIDATION_ERROR.

Problem and expected behavior

mcp doctor parses its own output options in parseOutputArguments (src/mcpDoctor.ts). That parser sent an absent or empty --format candidate down the same branch as an unsupported name, and runProductionMcpDoctorCli always set code: "VALIDATION_ERROR". Expected behavior: an absent or empty value is a missing value, reported before the diagnostic starts, with exit status 1.

Change and scope

src/mcpDoctor.ts:
- The failure variant of the parse result now carries its own code.
- An undefined or "" --format candidate returns MISSING_OUTPUT_VALUE.
- An unsupported value and an unknown option keep VALIDATION_ERROR.
- The CLI entry passes parsed.code through instead of hard-coding it.
src/cliOutput.ts: the existing missing-value message is extracted into missingCliOutputValueMessage(flag). The shared CLI and doctor now produce the message from one owner; the text is unchanged.
tests/boundary/cli/mcpDoctorHelpCli.test.ts: one boundary test covers --format, --format=, and both forms after --json. The existing --format bogus case remains the VALIDATION_ERROR control.

Not included:

Doctor keeps its bare {code, message} error shape rather than the {ok, error} envelope that capabilities uses. Envelope and selector preservation on argument errors is the scope of #2693, which touches the same function but keeps VALIDATION_ERROR for this case.
--format --help still reports an invalid format, as the existing test and code comment require.

Contribution scope: a CLI fix within existing boundaries; no maintainer scope decision required.

Contract and boundary impact

Semantic owner and earliest changed stage: mcp doctor argument parsing (parseOutputArguments), before the diagnostic starts.
Contribution scope fit and linked maintainer decision: not applicable (ordinary fix).
CLI and MCP/tool-catalog contract: the mcp doctor error code for an absent or empty --format changes from VALIDATION_ERROR to the documented MISSING_OUTPUT_VALUE. Exit status (1), output format selection, and error shape are unchanged. No MCP tool or catalog change.
Provider, bridge, target-format, or platform compatibility: none.
Evidence, artifact, provenance, or reconstruction contract: none.
Target selection, authority, upstream behavior, and cleanup details (if applicable): not applicable; the request fails before any child process starts.
Generated metadata, package, or installation impact: none.
Read existing files or captured data.
Launch or attach to a process.
Inject instrumentation or run scripts/code.
Change process memory, registers, files, or configuration.
Contact network services.
Recover protected code or work around protections.
Documentation or usability only; no target interaction.
Not sure yet; investigation or maintainer guidance needed.

Evidence and regression coverage

Tests added or updated: reports an absent or empty --format value as a missing output value in tests/boundary/cli/mcpDoctorHelpCli.test.ts.

Base reproduction or other evidence: before the fix, the new test failed on base c106cf20c with the reported output:

- "stdout": "code: MISSING_OUTPUT_VALUE
- message: \"--format requires a value, as in --format <value> or --format=<value>.\"
+ "stdout": "code: VALIDATION_ERROR
+ message: \"Invalid output format: missing\"

The other 4 tests in that file passed on base.

User-visible CLI output after the fix (exit 1 and empty stderr for every command):

$ rea mcp doctor --format
code: MISSING_OUTPUT_VALUE
message: "--format requires a value, as in --format <value> or --format=<value>."
$ rea mcp doctor --format=
code: MISSING_OUTPUT_VALUE
message: "--format requires a value, as in --format <value> or --format=<value>."
$ rea mcp doctor --json --format
{"code":"MISSING_OUTPUT_VALUE","message":"--format requires a value, as in --format <value> or --format=<value>."}
$ rea mcp doctor --json --format=
{"code":"MISSING_OUTPUT_VALUE","message":"--format requires a value, as in --format <value> or --format=<value>."}
$ rea mcp doctor --format bogus
code: VALIDATION_ERROR
message: "Invalid output format: bogus"
$ rea capabilities --format
{"ok":false,"error":{"code":"MISSING_OUTPUT_VALUE","message":"--format requires a value, as in --format <value> or --format=<value>."}}

Remaining proof gaps: not run on Linux or macOS locally (CI covers Linux). Other valued doctor options do not exist; --full-output takes no value.

For evidence-bearing changes: not applicable.

Validation performed

All runs on Windows 11 x64 with Node v24.19.0, from a source checkout with native/windows/build/ restored from the rea-agents@6.7.0 tarball (ignored files, not committed).

npm run test:focused -- tests/boundary/cli/mcpDoctorHelpCli.test.ts: failed 1/5 before the fix (output above); passed 5/5 after.
npm run test:focused -- tests/boundary/cli/cliOutput.test.ts tests/boundary/cli/dispatcher.test.ts tests/boundary/cli/mcpDoctorHelpCli.test.ts tests/boundary/mcp/mcpDoctor.test.ts: 4 files, 72/72 passed.
npm run check:fast (typecheck, lint, module boundaries): passed, 2/2 Turbo tasks.
node scripts/rea.mjs … for the six commands above: output as shown.

Compatibility, safety, and release

Breaking changes or migration steps: none intended. A caller that matched VALIDATION_ERROR for an absent or empty doctor --format value now receives the documented MISSING_OUTPUT_VALUE. The exit status is unchanged.
Real Hopper/Ghidra, browser, or OS coverage: Windows 11 x64; no provider needed (the request fails during argument parsing).
Package or release metadata impact: none.
Security, privacy, process, or containment review: no new process, file, or network behavior.

Author readiness

Human owner: @ezrabrilliant

I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work.
I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps.
I declare this PR ready for initial maintainer review.

Before merge

This PR addresses a concrete problem or an agreed enhancement.
Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff.
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.

🤖 Generated with Claude Code

https://claude.ai/code/session_01LjhoPGpqAwHwcCgectzRsp

_{🔄 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/6489 **Author:** [@ezrabrilliant](https://github.com/ezrabrilliant) **Created:** 10/23/2026 **Status:** ✅ Merged **Merged:** 10/23/2026 **Merged by:** [@morluto](https://github.com/morluto) **Base:** `main` ← **Head:** `fix/mcp-doctor-missing-format` --- ### 📝 Commits (1) - [`0cac844`](https://github.com/morluto/rea/commit/0cac844f0c3d1c22824d1b856fcf1a64078d6e72) fix(doctor): report a missing --format value as MISSING_OUTPUT_VALUE ### 📊 Changes **3 files changed** (+49 additions, -3 deletions) <details> <summary>View changed files</summary> 📝 `src/cliOutput.ts` (+5 -1) 📝 `src/mcpDoctor.ts` (+14 -2) 📝 `tests/boundary/cli/mcpDoctorHelpCli.test.ts` (+30 -0) </details> ### 📄 Description ## Summary Fixes #6455. `rea mcp doctor --format` and `rea mcp doctor --format=` returned `VALIDATION_ERROR` with `Invalid output format: missing`. [docs/cli.md](https://github.com/morluto/rea/blob/main/docs/cli.md) documents `MISSING_OUTPUT_VALUE` for a valued output flag given without a value, and `capabilities` already returns that code. `mcp doctor` now returns `MISSING_OUTPUT_VALUE` with the same message `capabilities` uses. A format value that is present but unsupported still returns `VALIDATION_ERROR`. ## Problem and expected behavior `mcp doctor` parses its own output options in `parseOutputArguments` (`src/mcpDoctor.ts`). That parser sent an absent or empty `--format` candidate down the same branch as an unsupported name, and `runProductionMcpDoctorCli` always set `code: "VALIDATION_ERROR"`. Expected behavior: an absent or empty value is a missing value, reported before the diagnostic starts, with exit status 1. ## Change and scope - `src/mcpDoctor.ts`: - The failure variant of the parse result now carries its own `code`. - An `undefined` or `""` `--format` candidate returns `MISSING_OUTPUT_VALUE`. - An unsupported value and an unknown option keep `VALIDATION_ERROR`. - The CLI entry passes `parsed.code` through instead of hard-coding it. - `src/cliOutput.ts`: the existing missing-value message is extracted into `missingCliOutputValueMessage(flag)`. The shared CLI and doctor now produce the message from one owner; the text is unchanged. - `tests/boundary/cli/mcpDoctorHelpCli.test.ts`: one boundary test covers `--format`, `--format=`, and both forms after `--json`. The existing `--format bogus` case remains the `VALIDATION_ERROR` control. Not included: - Doctor keeps its bare `{code, message}` error shape rather than the `{ok, error}` envelope that `capabilities` uses. Envelope and selector preservation on argument errors is the scope of #2693, which touches the same function but keeps `VALIDATION_ERROR` for this case. - `--format --help` still reports an invalid format, as the existing test and code comment require. Contribution scope: a CLI fix within existing boundaries; no maintainer scope decision required. ## Contract and boundary impact - Semantic owner and earliest changed stage: `mcp doctor` argument parsing (`parseOutputArguments`), before the diagnostic starts. - Contribution scope fit and linked maintainer decision: not applicable (ordinary fix). - CLI and MCP/tool-catalog contract: the `mcp doctor` error code for an absent or empty `--format` changes from `VALIDATION_ERROR` to the documented `MISSING_OUTPUT_VALUE`. Exit status (1), output format selection, and error shape are unchanged. No MCP tool or catalog change. - Provider, bridge, target-format, or platform compatibility: none. - Evidence, artifact, provenance, or reconstruction contract: none. - Target selection, authority, upstream behavior, and cleanup details (if applicable): not applicable; the request fails before any child process starts. - Generated metadata, package, or installation impact: none. - [ ] Read existing files or captured data. - [ ] Launch or attach to a process. - [ ] Inject instrumentation or run scripts/code. - [ ] Change process memory, registers, files, or configuration. - [ ] Contact network services. - [ ] Recover protected code or work around protections. - [x] Documentation or usability only; no target interaction. - [ ] Not sure yet; investigation or maintainer guidance needed. ## Evidence and regression coverage - Tests added or updated: `reports an absent or empty --format value as a missing output value` in `tests/boundary/cli/mcpDoctorHelpCli.test.ts`. - Base reproduction or other evidence: before the fix, the new test failed on base `c106cf20c` with the reported output: ```text - "stdout": "code: MISSING_OUTPUT_VALUE - message: \"--format requires a value, as in --format <value> or --format=<value>.\" + "stdout": "code: VALIDATION_ERROR + message: \"Invalid output format: missing\" ``` The other 4 tests in that file passed on base. - User-visible CLI output after the fix (exit 1 and empty stderr for every command): ```text $ rea mcp doctor --format code: MISSING_OUTPUT_VALUE message: "--format requires a value, as in --format <value> or --format=<value>." $ rea mcp doctor --format= code: MISSING_OUTPUT_VALUE message: "--format requires a value, as in --format <value> or --format=<value>." $ rea mcp doctor --json --format {"code":"MISSING_OUTPUT_VALUE","message":"--format requires a value, as in --format <value> or --format=<value>."} $ rea mcp doctor --json --format= {"code":"MISSING_OUTPUT_VALUE","message":"--format requires a value, as in --format <value> or --format=<value>."} $ rea mcp doctor --format bogus code: VALIDATION_ERROR message: "Invalid output format: bogus" $ rea capabilities --format {"ok":false,"error":{"code":"MISSING_OUTPUT_VALUE","message":"--format requires a value, as in --format <value> or --format=<value>."}} ``` - Remaining proof gaps: not run on Linux or macOS locally (CI covers Linux). Other valued doctor options do not exist; `--full-output` takes no value. For evidence-bearing changes: not applicable. ## Validation performed All runs on Windows 11 x64 with Node v24.19.0, from a source checkout with `native/windows/build/` restored from the `rea-agents@6.7.0` tarball (ignored files, not committed). - `npm run test:focused -- tests/boundary/cli/mcpDoctorHelpCli.test.ts`: failed 1/5 before the fix (output above); passed 5/5 after. - `npm run test:focused -- tests/boundary/cli/cliOutput.test.ts tests/boundary/cli/dispatcher.test.ts tests/boundary/cli/mcpDoctorHelpCli.test.ts tests/boundary/mcp/mcpDoctor.test.ts`: 4 files, 72/72 passed. - `npm run check:fast` (typecheck, lint, module boundaries): passed, 2/2 Turbo tasks. - `node scripts/rea.mjs …` for the six commands above: output as shown. ## Compatibility, safety, and release - Breaking changes or migration steps: none intended. A caller that matched `VALIDATION_ERROR` for an absent or empty doctor `--format` value now receives the documented `MISSING_OUTPUT_VALUE`. The exit status is unchanged. - Real Hopper/Ghidra, browser, or OS coverage: Windows 11 x64; no provider needed (the request fails during argument parsing). - Package or release metadata impact: none. - Security, privacy, process, or containment review: no new process, file, or network behavior. ## Author readiness Human owner: @ezrabrilliant - [x] I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work. - [x] I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps. - [x] I declare this PR ready for initial maintainer review. ## Before merge - [ ] This PR addresses a concrete problem or an agreed enhancement. - [ ] Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff. - [ ] 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. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01LjhoPGpqAwHwcCgectzRsp --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-11-01 21:47:21 +00:00

closed this issue
added the
pull-request
label

bsakaguchi referenced this issue

2026-11-05 01:48:01 +00:00

[PR #7367] fix(mcp): preserve HTTP listener recovery guidance #7836

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.

Dependencies

No dependencies set.

Reference

morluto/rea#7367

No description provided.

Rows
Columns