morluto/rea

Fork 0

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

[GH-ISSUE #7601] [Bug] Root and command help omit the documented global --json switch #4533

New issue

Open

opened 2026-10-31 00:50:33 +00:00 by bsakaguchi · 1 comment

bsakaguchi commented

2026-10-31 00:50:33 +00:00

Owner

Originally created by @coygeek on GitHub (Oct 27, 2026).
Original GitHub issue: https://github.com/morluto/rea/issues/7601

Before submitting

I searched the open and closed issues for a related report.
I removed credentials, tokens, private paths, and sensitive target data.

Area

CLI

Observed behavior

node scripts/rea.mjs capabilities --help prints a Global Options section without --json. Root help has the same omission. Both help requests succeed, and node scripts/rea.mjs capabilities --json succeeds with parseable JSON output. The help does advertise the working alternative --format json.

This is a help-content omission for a documented, accepted global switch. It does not prevent JSON output. The separately rendered mcp doctor --help lists --json, so the omission does not affect every help page.

Reproduction

Use the source baseline below with its locked dependencies and prepared runtime. Put Node.js v24.22.1 on PATH. This verification used the already-built checkout without rebuilding it; no analysis target or provider fixture is needed.

From the checkout root, run this isolated probe:

python3 -I - <<'PYTHON'
import json, os, pathlib, re, subprocess, tempfile

node = subprocess.check_output(["which", "node"], text=True).strip()
assert subprocess.check_output([node, "--version"], text=True).strip() == "v24.22.1"
with tempfile.TemporaryDirectory() as work:
    root = pathlib.Path(work)
    env = {"PATH": os.environ["PATH"], "NO_COLOR": "1"}
    for key, name in {
        "HOME": "home", "XDG_CONFIG_HOME": "config",
        "XDG_CACHE_HOME": "cache", "XDG_DATA_HOME": "data",
        "XDG_STATE_HOME": "state", "TMPDIR": "tmp",
    }.items():
        directory = root / name
        directory.mkdir()
        env[key] = str(directory)
    for args in [["--help"], ["capabilities", "--help"],
                 ["capabilities", "--json"],
                 ["capabilities", "--format", "json"]]:
        result = subprocess.run([node, "scripts/rea.mjs", *args],
                                env=env, capture_output=True, text=True,
                                timeout=45)
        assert result.returncode == 0, result.stderr or result.stdout
        assert result.stderr == "", result.stderr
        if "--help" in args:
            listed = bool(re.search(r"^  --json(?:\s|$)", result.stdout, re.M))
            print(" ".join(args), "exit=0", "json_option_listed=" + str(listed))
        else:
            json.loads(result.stdout)
            print(" ".join(args), "exit=0 valid_json=True")
PYTHON

Both help checks print json_option_listed=False; both output controls print valid_json=True. The original independent replay reproduced the capabilities help omission in 3/3 runs and the root omission once. The self-contained probe above was also executed once successfully.

Expected behavior

Root and ordinary command help should include the documented global --json switch, optionally explaining its relationship to --format json.

The CLI guide directs callers to command help to confirm available options, recommends --json when saving results for JSON consumers, and explicitly identifies it as a global selector equivalent to --format json. The precise documentation and implementation references are in Evidence below. The guide does not explicitly require every alias to be listed; this report concerns discoverability of the switch it recommends to users.

Impact and scope

P3: the observed effect is incomplete help text. JSON output remains available through both spellings, and the help-advertised --format json is a verified practical alternative. No command-result corruption, failed analysis, or broken script was observed.

Root and capabilities help were checked. The completion callback also advertises --json. mcp doctor --help includes the switch and is an explicit exception. Other command pages and LLM manifests were not exhaustively checked.

REA version

Exact node scripts/rea.mjs --version stdout:

6.8.0

The output ends with a newline. Source baseline: 65f1c447344a423fa2785847dbcea1e9a9e2454a.

Runtime and platform

Node.js v24.22.1; macOS 27.0.1; darwin arm64. Locked Incur 0.6.1. No GUI or analysis provider was launched.

Interface

CLI

Earliest failure stage

Transport or result projection

Relevant output or evidence

Observed node scripts/rea.mjs capabilities --help output, exit 0 with empty stderr:

Global Options:
  --filter-output <keys>              Filter output by key paths (e.g. foo,bar.baz,a[0,3])
  --format <toon|json|yaml|md|jsonl>  Output format
  --full-output                       Show full output envelope
  --help                              Show help
  --llms, --llms-full                 Print LLM-readable manifest
  --schema                            Show JSON Schema for command
  --token-count                       Print token count of output (instead of output)
  --token-limit <n>                   Limit output to n tokens
  --token-offset <n>                  Skip first n tokens of output

Both node scripts/rea.mjs capabilities --json and node scripts/rea.mjs capabilities --format json exited 0 with empty stderr and JSON objects. The supported completion request COMPLETE=bash _COMPLETE_INDEX=2 node scripts/rea.mjs -- rea capabilities -- exited 0 and included --json among its candidates.

Source references at the stated baseline:

docs/cli.md:172-173,405: help is the documented place to confirm available options and output arguments.
docs/cli.md:954-962,988-991: recommended JSON output syntax and explicit global-selector equivalence.
src/cliBuiltinArguments.ts:9-29: --json belongs to the output-switch and builtin sets.
src/cli/completions.ts:20-42: completion globals include the switch while excluding an explicitly internal flag.
scripts/rea.mjs:135-145 and src/cli.ts:95-117: public launcher dispatches ordinary commands through the framework CLI.
node_modules/incur/src/Help.ts:412-439: the locked dependency's global-help list lacks a --json entry.
node_modules/incur/src/Cli.ts:2806-2808: its builtin parser accepts bare --json and selects JSON.

Analysis or suspected cause

Source-derived: the shared help list and parser have separate flag definitions. The parser supports --json; the list rendered under Global Options omits it. This explains the observed ordinary-help discrepancy. No repair was implemented or tested.

Additional context

Open and closed issues, issue comments, and open/closed/merged PRs were searched. Closed #5526 restored missing global flags in shell completion; its closure confirms completion behavior, not this help-list entry. Open #7585 concerns unsupported flags offered for MCP doctor, and #7386 concerns repeated HTTP option values. Their restoration checks differ from showing an already supported switch in ordinary help.

The historical Cutter --json=true/false syntax is explicitly retired in docs/cli.md:993-995; its rejection is excluded from this report. No last-known-good version was established, and no regression is claimed. No project test suite was run; the evidence is from direct public-launcher replays and the locked source.

Triage assessment

Impact level: P3
Assessment status: supported
Impact basis: The demonstrated discrepancy affects help content while the documented output operation succeeds through both spellings; no consequential behavior failure was demonstrated.
Workaround status: available
Workaround basis: The help lists --format with json among its choices, and capabilities --format json was independently executed successfully with parseable JSON output.

Originally created by @coygeek on GitHub (Oct 27, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/7601 ### Before submitting - [x] I searched the open and closed issues for a related report. - [x] I removed credentials, tokens, private paths, and sensitive target data. ### Area CLI ### Observed behavior `node scripts/rea.mjs capabilities --help` prints a Global Options section without `--json`. Root help has the same omission. Both help requests succeed, and `node scripts/rea.mjs capabilities --json` succeeds with parseable JSON output. The help does advertise the working alternative `--format json`. This is a help-content omission for a documented, accepted global switch. It does not prevent JSON output. The separately rendered `mcp doctor --help` lists `--json`, so the omission does not affect every help page. ### Reproduction 1. Use the source baseline below with its locked dependencies and prepared runtime. Put Node.js v24.22.1 on PATH. This verification used the already-built checkout without rebuilding it; no analysis target or provider fixture is needed. 2. From the checkout root, run this isolated probe: ```sh python3 -I - <<'PYTHON' import json, os, pathlib, re, subprocess, tempfile node = subprocess.check_output(["which", "node"], text=True).strip() assert subprocess.check_output([node, "--version"], text=True).strip() == "v24.22.1" with tempfile.TemporaryDirectory() as work: root = pathlib.Path(work) env = {"PATH": os.environ["PATH"], "NO_COLOR": "1"} for key, name in { "HOME": "home", "XDG_CONFIG_HOME": "config", "XDG_CACHE_HOME": "cache", "XDG_DATA_HOME": "data", "XDG_STATE_HOME": "state", "TMPDIR": "tmp", }.items(): directory = root / name directory.mkdir() env[key] = str(directory) for args in [["--help"], ["capabilities", "--help"], ["capabilities", "--json"], ["capabilities", "--format", "json"]]: result = subprocess.run([node, "scripts/rea.mjs", *args], env=env, capture_output=True, text=True, timeout=45) assert result.returncode == 0, result.stderr or result.stdout assert result.stderr == "", result.stderr if "--help" in args: listed = bool(re.search(r"^ --json(?:\s|$)", result.stdout, re.M)) print(" ".join(args), "exit=0", "json_option_listed=" + str(listed)) else: json.loads(result.stdout) print(" ".join(args), "exit=0 valid_json=True") PYTHON ``` 3. Both help checks print `json_option_listed=False`; both output controls print `valid_json=True`. The original independent replay reproduced the capabilities help omission in 3/3 runs and the root omission once. The self-contained probe above was also executed once successfully. ### Expected behavior Root and ordinary command help should include the documented global `--json` switch, optionally explaining its relationship to `--format json`. The CLI guide directs callers to command help to confirm available options, recommends `--json` when saving results for JSON consumers, and explicitly identifies it as a global selector equivalent to `--format json`. The precise documentation and implementation references are in Evidence below. The guide does not explicitly require every alias to be listed; this report concerns discoverability of the switch it recommends to users. ### Impact and scope P3: the observed effect is incomplete help text. JSON output remains available through both spellings, and the help-advertised `--format json` is a verified practical alternative. No command-result corruption, failed analysis, or broken script was observed. Root and capabilities help were checked. The completion callback also advertises `--json`. `mcp doctor --help` includes the switch and is an explicit exception. Other command pages and LLM manifests were not exhaustively checked. ### REA version Exact `node scripts/rea.mjs --version` stdout: ```text 6.8.0 ``` The output ends with a newline. Source baseline: `65f1c447344a423fa2785847dbcea1e9a9e2454a`. ### Runtime and platform Node.js v24.22.1; macOS 27.0.1; darwin arm64. Locked Incur 0.6.1. No GUI or analysis provider was launched. ### Interface CLI ### Earliest failure stage Transport or result projection ### Relevant output or evidence Observed `node scripts/rea.mjs capabilities --help` output, exit 0 with empty stderr: ```text Global Options: --filter-output <keys> Filter output by key paths (e.g. foo,bar.baz,a[0,3]) --format <toon|json|yaml|md|jsonl> Output format --full-output Show full output envelope --help Show help --llms, --llms-full Print LLM-readable manifest --schema Show JSON Schema for command --token-count Print token count of output (instead of output) --token-limit <n> Limit output to n tokens --token-offset <n> Skip first n tokens of output ``` Both `node scripts/rea.mjs capabilities --json` and `node scripts/rea.mjs capabilities --format json` exited 0 with empty stderr and JSON objects. The supported completion request `COMPLETE=bash _COMPLETE_INDEX=2 node scripts/rea.mjs -- rea capabilities --` exited 0 and included `--json` among its candidates. Source references at the stated baseline: - `docs/cli.md:172-173,405`: help is the documented place to confirm available options and output arguments. - `docs/cli.md:954-962,988-991`: recommended JSON output syntax and explicit global-selector equivalence. - `src/cliBuiltinArguments.ts:9-29`: `--json` belongs to the output-switch and builtin sets. - `src/cli/completions.ts:20-42`: completion globals include the switch while excluding an explicitly internal flag. - `scripts/rea.mjs:135-145` and `src/cli.ts:95-117`: public launcher dispatches ordinary commands through the framework CLI. - `node_modules/incur/src/Help.ts:412-439`: the locked dependency's global-help list lacks a `--json` entry. - `node_modules/incur/src/Cli.ts:2806-2808`: its builtin parser accepts bare `--json` and selects JSON. ### Analysis or suspected cause Source-derived: the shared help list and parser have separate flag definitions. The parser supports `--json`; the list rendered under Global Options omits it. This explains the observed ordinary-help discrepancy. No repair was implemented or tested. ### Additional context Open and closed issues, issue comments, and open/closed/merged PRs were searched. Closed [#5526](https://github.com/morluto/rea/issues/5526) restored missing global flags in shell completion; its closure confirms completion behavior, not this help-list entry. Open [#7585](https://github.com/morluto/rea/issues/7585) concerns unsupported flags offered for MCP doctor, and [#7386](https://github.com/morluto/rea/issues/7386) concerns repeated HTTP option values. Their restoration checks differ from showing an already supported switch in ordinary help. The historical Cutter `--json=true/false` syntax is explicitly retired in `docs/cli.md:993-995`; its rejection is excluded from this report. No last-known-good version was established, and no regression is claimed. No project test suite was run; the evidence is from direct public-launcher replays and the locked source. ## Triage assessment - Impact level: P3 - Assessment status: supported - Impact basis: The demonstrated discrepancy affects help content while the documented output operation succeeds through both spellings; no consequential behavior failure was demonstrated. - Workaround status: available - Workaround basis: The help lists --format with json among its choices, and capabilities --format json was independently executed successfully with parseable JSON output.

bsakaguchi commented

2026-10-31 00:50:34 +00:00

Author

Owner

@amarthya-14 commented on GitHub (Oct 29, 2026):

Root cause is upstream in incur: the Global Options list in help is hardcoded in incur's Help.ts and leaves out --json, even though incur's own parser accepts --json as a shorthand for --format json (rea 6.8.0 ships incur 0.6.1; node_modules/incur/dist/Help.js, globalOptionsLines). So every incur-based CLI has this gap, and rea's mcp doctor --help lists it only because that page is rendered separately.

I've opened a fix upstream: https://github.com/wevm/incur/pull/282. Once it's released, bumping incur here should make root and command help list --json with no rea code changes.

@amarthya-14 commented on GitHub (Oct 29, 2026): Root cause is upstream in incur: the Global Options list in help is hardcoded in incur's `Help.ts` and leaves out `--json`, even though incur's own parser accepts `--json` as a shorthand for `--format json` (rea 6.8.0 ships incur 0.6.1; `node_modules/incur/dist/Help.js`, `globalOptionsLines`). So every incur-based CLI has this gap, and rea's `mcp doctor --help` lists it only because that page is rendered separately. I've opened a fix upstream: https://github.com/wevm/incur/pull/282. Once it's released, bumping incur here should make root and command help list `--json` with no rea code changes.

bsakaguchi referenced this issue

2026-10-31 01:13:22 +00:00

[PR #4543] [CLOSED] fix(native): preserve class metadata beside malformed Objective-C ivars #6295

bsakaguchi referenced this issue

2026-10-31 01:13:23 +00:00

[PR #4545] [CLOSED] fix(objc): isolate empty Objective-C ivar names #6298

bsakaguchi referenced this issue

2026-10-31 01:13:24 +00:00

[PR #4548] [CLOSED] fix(native): reject empty Objective-C ivar names in class metadata #6300