morluto/rea

Fork 0

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

[GH-ISSUE #7138] [Docs] CLI JSON request arguments do not document reading standard input with `-` #4284

New issue

Closed

opened 2026-10-31 00:48:30 +00:00 by bsakaguchi · 3 comments

bsakaguchi commented

2026-10-31 00:48:30 +00:00

Owner

Originally created by @viniciusdsandrade on GitHub (Oct 25, 2026).
Original GitHub issue: https://github.com/morluto/rea/issues/7138

Before submitting

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

Documentation location

docs/cli.md ("Run a command"), and the --help text of CLI arguments described as inline JSON or a JSON file path.

Problem

#5486 asked for - to mean standard input for CLI commands whose input is a structured JSON request document. Its acceptance criteria include "The behavior is documented per command". #7040 implemented the behavior, but the merged change touches no documentation: git show --stat 4b045e8f2 lists only src/ and tests/ files.

Current state on main (25f0f9934):

parseCliJsonInput reads standard input when the argument is exactly - (src/cliJsonInput.ts:72). The read is capped by DEFAULT_MAX_STDIN_BYTES, 8 MiB (src/cliJsonInput.ts:127, :141). A leading byte-order mark and invalid UTF-8 are refused (src/application/Utf8JsonInput.ts:14, :83-84, :88).
docs/cli.md describes these requests only as files (rea inspect-analysis-view app-view.json, "The request can also name the saved file instead of embedding it") and never mentions -. Searching it for stdin or standard input matches only the signal note at line 747.
The argument descriptions read "Inline workflow JSON or JSON file path" (for example src/cli/analysisViewCommands.ts:84), so --help does not mention it either.

A reader cannot learn that a request can be piped, that a piped request is limited to 8 MiB while a file is read through the streaming parser, or that a byte-order mark is refused.

Expected content

A short passage in docs/cli.md, next to the existing request-file example. Proposed content, derived from the source above:

an argument that takes inline JSON or a JSON file path also accepts - to read the request from standard input;
standard input is read once as one UTF-8 JSON document without a byte-order mark, at most 8 MiB, and a larger request belongs in a file;
one example, for instance jq -nc '{source: {kind: "evidence-file", path: "app-evidence.json"}, view: {kind: "summary"}}' | rea inspect-analysis-view -.

Whether the shared argument descriptions should also mention - is a separate question for the maintainers, because many commands reuse them.

Supporting evidence

Behavior: src/cliJsonInput.ts:71-73 and :129-245; refusals: src/application/Utf8JsonInput.ts.
Public CLI coverage: tests/boundary/cli/cliJsonStdinCli.test.ts pipes JSON to compare-wasm-interfaces - and environment-serve -.
This evidence is derived from the source and the documentation. I did not run the CLI.

Additional context

Related: #5486, #7040.

Originally created by @viniciusdsandrade on GitHub (Oct 25, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/7138 ### Before submitting - [x] I searched the existing issues for a related documentation report. - [x] I removed credentials, tokens, private paths, and sensitive target data. ### Documentation location `docs/cli.md` ("Run a command"), and the `--help` text of CLI arguments described as inline JSON or a JSON file path. ### Problem #5486 asked for `-` to mean standard input for CLI commands whose input is a structured JSON request document. Its acceptance criteria include "The behavior is documented per command". #7040 implemented the behavior, but the merged change touches no documentation: `git show --stat 4b045e8f2` lists only `src/` and `tests/` files. Current state on `main` (25f0f9934): - `parseCliJsonInput` reads standard input when the argument is exactly `-` (`src/cliJsonInput.ts:72`). The read is capped by `DEFAULT_MAX_STDIN_BYTES`, 8 MiB (`src/cliJsonInput.ts:127`, `:141`). A leading byte-order mark and invalid UTF-8 are refused (`src/application/Utf8JsonInput.ts:14`, `:83-84`, `:88`). - `docs/cli.md` describes these requests only as files (`rea inspect-analysis-view app-view.json`, "The request can also name the saved file instead of embedding it") and never mentions `-`. Searching it for `stdin` or `standard input` matches only the signal note at line 747. - The argument descriptions read "Inline workflow JSON or JSON file path" (for example `src/cli/analysisViewCommands.ts:84`), so `--help` does not mention it either. A reader cannot learn that a request can be piped, that a piped request is limited to 8 MiB while a file is read through the streaming parser, or that a byte-order mark is refused. ### Expected content A short passage in `docs/cli.md`, next to the existing request-file example. Proposed content, derived from the source above: - an argument that takes inline JSON or a JSON file path also accepts `-` to read the request from standard input; - standard input is read once as one UTF-8 JSON document without a byte-order mark, at most 8 MiB, and a larger request belongs in a file; - one example, for instance `jq -nc '{source: {kind: "evidence-file", path: "app-evidence.json"}, view: {kind: "summary"}}' | rea inspect-analysis-view -`. Whether the shared argument descriptions should also mention `-` is a separate question for the maintainers, because many commands reuse them. ### Supporting evidence - Behavior: `src/cliJsonInput.ts:71-73` and `:129-245`; refusals: `src/application/Utf8JsonInput.ts`. - Public CLI coverage: `tests/boundary/cli/cliJsonStdinCli.test.ts` pipes JSON to `compare-wasm-interfaces -` and `environment-serve -`. - This evidence is derived from the source and the documentation. I did not run the CLI. ### Additional context Related: #5486, #7040.

bsakaguchi commented

2026-10-31 00:48:31 +00:00

Author

Owner

@XinwangTao commented on GitHub (Oct 25, 2026):

Good catch - documenting the - stdin convention for JSON request arguments is genuinely useful, since most CLI docs only show file paths. A short pipe example (e.g. echo '{"args":...}' | rea tool --args -) in the same section would make the behavior immediately discoverable.

@XinwangTao commented on GitHub (Oct 25, 2026): Good catch - documenting the `-` stdin convention for JSON request arguments is genuinely useful, since most CLI docs only show file paths. A short pipe example (e.g. `echo '{"args":...}' | rea tool --args -`) in the same section would make the behavior immediately discoverable.

bsakaguchi commented

2026-10-31 00:48:31 +00:00

Author

Owner

@XinwangTao commented on GitHub (Oct 25, 2026):

Agreed, the acceptance criteria in #5486 explicitly asked for per-command documentation, so shipping the - behavior without touching docs/cli.md leaves the feature undiscoverable. One concrete suggestion: since multiple commands share the inline-JSON/JSON-file/'-' trio, document it once in a small shared section (e.g. 'Reading request input') and reference it from each affected command's --help/argument table, plus add a one-line example like rea analyze - < request.json so users can find it quickly.

@XinwangTao commented on GitHub (Oct 25, 2026): Agreed, the acceptance criteria in #5486 explicitly asked for per-command documentation, so shipping the - behavior without touching docs/cli.md leaves the feature undiscoverable. One concrete suggestion: since multiple commands share the inline-JSON/JSON-file/'-' trio, document it once in a small shared section (e.g. 'Reading request input') and reference it from each affected command's --help/argument table, plus add a one-line example like `rea analyze - < request.json` so users can find it quickly.

bsakaguchi referenced this issue

2026-10-31 01:12:18 +00:00

[PR #4284] [CLOSED] fix(clients): remove a sole JSONC registration with a trailing comma #6156

bsakaguchi closed this issue

2026-11-04 11:07:27 +00:00

bsakaguchi commented

2026-11-05 04:41:33 +00:00

Author

Owner

@XinwangTao commented on GitHub (Nov 5, 2026):

Great — the merged docs now cover the - stdin convention, the 8 MiB cap and the BOM/UTF-8 refusals exactly as proposed in #5486's acceptance criteria. The pipe example makes it discoverable. Thanks for closing this out; marking as completed.

@XinwangTao commented on GitHub (Nov 5, 2026): Great — the merged docs now cover the `-` stdin convention, the 8 MiB cap and the BOM/UTF-8 refusals exactly as proposed in #5486's acceptance criteria. The pipe example makes it discoverable. Thanks for closing this out; marking as completed.

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#4284

No description provided.

Rows
Columns

[GH-ISSUE #7138] [Docs] CLI JSON request arguments do not document reading standard input with - #4284

Before submitting

Documentation location

Problem

Expected content

Supporting evidence

Additional context

[GH-ISSUE #7138] [Docs] CLI JSON request arguments do not document reading standard input with `-` #4284