feat(body): accept --body @file and validate JSON client-side

[dspangen]

--body @file.json (curl-style) now works, and bodies are validated as JSON client-side before any network call. Previously a file path passed to --body was POSTed literally and the server's Invalid JSON 400 read as a body-shape problem, sending callers back to --schema (6 audited incidents).

• --body @path reads the file (10 MB cap, ~/ expansion, @- = stdin); missing file is a clear local error.
• Invalid JSON fails locally; a path-shaped value gets a transport hint: read the file instead: --body @/tmp/body.json.
• --body '' is now an error (almost always an unexpanded "$BODY"); omitting the flag still sends no body.
• Bytes are never re-serialized — what you pass is what gets sent. Multipart endpoints skip JSON validation but keep the path hint.

Details: behavior, edge cases, and verification

Problem

omni ai generate-query --body @/tmp/body.json     # curl syntax
omni ai generate-query --body /tmp/body.json      # bare path

Both were sent to the API verbatim as the body. The server replied {"detail": "Bad Request: Invalid JSON", "status": 400} — which reads as a body-shape problem, so the agent went back to --schema, rebuilt the JSON, and hit the same wall. The mistake was never about shape; it was about transport.

Changes

• --body @path/to/file.json reads the file. Same 10 MB cap as stdin, ~/ expanded (shells don't expand it after @), and @- accepted as curl's spelling of stdin. A missing or unreadable file is a client-side error naming the path.

• Bodies are checked with json.Valid before the request is made. No network call happens on a bad body. Bytes are never re-serialized — what you pass is what gets sent, field order and all.

• A path-shaped --body gets a transport hint, not a parse error:

  Error: --body looks like a file path, not a request body: /tmp/body.json
  read the file instead: --body @/tmp/body.json   (or --body - < /tmp/body.json)
  

  Triggered by a /, ./, ../, ~/ prefix or an existing file — including paths with spaces, which arrive unquoted from the shell and get re-quoted in the suggestion. Anything else malformed gets the parse error plus byte offset and surrounding snippet.

• --body '' is an error, not a bodiless request. Omitting the flag still sends no body.

• Applies identically to the hidden --json-body alias; errors name whichever flag was typed.

• The multipart/form-data upload operations skip JSON validation only (operationInfo.BodyNonJSON) — the transport checks still apply there, since --body @file is exactly what those endpoints need.

• Help text updated in generate.go, omni agent-help, and the README.

Body shorthand (omni ai search-omni-docs "question") is unaffected: it assembles its body with json.Marshal and sets --body internally, so it passes validation untouched. Shorthand commands also accept --body @file.

Verification

make build && make test — all packages pass, including the existing spec-coverage test over every operation in api/openapi.json.

25 tests in internal/openapi/body_input_test.go cover: @file expansion, missing / oversized / non-JSON @file, bare @, the file-path hint for all four path shapes plus a space-containing existing path, the parse diagnostic, flag naming, byte-identical passthrough of valid JSON (including whitespace and non-object bodies), the non-JSON media-type carve-out and its retained path hint, stdin via - and @-, empty sources, --body '' on both plain and shorthand commands, @file end-to-end through a generated cobra command, the executor not running on an invalid body, and both shorthand paths.

Manual check against a real binary:

$ omni ai search-omni-docs --body /tmp/body.json
Error: --body looks like a file path, not a request body: /tmp/body.json
read the file instead: --body @/tmp/body.json   (or --body - < /tmp/body.json)

$ omni ai search-omni-docs --body '{"question":"x",}'
Error: request body from --body is not valid JSON: invalid character '}' looking
for beginning of object key string (at byte 17, near "{\"question\":\"x\",}")

$ omni query run --body ''
Error: --body is empty; omit the flag to send no body

$ omni uploads create --body /tmp/upload.csv
Error: --body looks like a file path, not a request body: /tmp/upload.csv
read the file instead: --body @/tmp/upload.csv   (or --body - < /tmp/upload.csv)

$ omni ai search-omni-docs --body @/tmp/body.json    # reaches the API

🤖 Generated with Claude Code

https://claude.ai/code/session_014TwwKSAsAGPBToNb4iUe5s

[Copilot]

Pull request overview

Adds file-backed body input and client-side JSON validation to generated API commands.

Changes:

• Supports --body @file, @-, home expansion, and size limits.
• Validates JSON locally with clearer diagnostics.
• Adds comprehensive tests and updates help documentation.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
README.md	Documents body input options.
internal/openapi/generate.go	Integrates body resolution and media-type detection.
internal/openapi/body_shorthand.go	Handles explicit body flags with shorthand commands.
internal/openapi/body_input.go	Implements file reading, validation, and diagnostics.
internal/openapi/body_input_test.go	Tests body-input behavior and integration.
cmd/omni/agent_help.go	Updates agent-facing body guidance.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[n8agrin]

Code review found one bug.

internal/openapi/body_shorthand.go:363 — --body '' on shorthand commands doesn't reach the new "empty body" error.

flexibleArgs decides whether --body was passed by checking bodyFlag != "". An explicitly empty string looks the same as unset, so it falls through to requiring the shorthand positional arg count instead of just the path params. Reproduced on a build of this branch:

$ omni ai search-omni-docs --body ''
Error: accepts 1 arg(s), received 0

That's exactly the typo case (unexpanded --body "$VAR") this PR is meant to catch — on shorthand commands it never reaches the "--body is empty" message added at body_shorthand.go:332.

[n8agrin]

one finding from the bots

[dspangen]

@ernestoongaro #72 will land with this one.

[ernestoongaro]

Opened #82 into feat/body-file-input — the multipart review findings from #72 that 3d9b0e1 and 0827738 didn't already cover.

Two are real bugs: ~ was never expanded for binary field paths, so --file ~/people.csv failed with "no such file or directory" while --body @~/x.json worked; and --body null decoded into a nil map, panicking with assignment to entry in nil map on the first generated flag merged into it. Three more are latent on the current spec — flag-name collisions could register the same pflag twice and panic at startup, array/object flag values decoded into interface{} so an object passed where the schema says array and trailing data was dropped, and requestBodyMediaType could prefer a schema-less application/json entry over a real multipart definition.

Regression test per fix; go test ./... green on top of 5eea40d. Stacked as a PR rather than pushed onto your branch, matching #74/#77/#79.

Closing #72 as superseded — its multipart commit already landed here as ffebcee.

One thing I left alone: operationInfo.bodyFlagIsJSON (generate.go:448) is dead now that 3d9b0e1 dropped resolveBody's validateJSON parameter, and its comment still describes the old behavior. Yours to cut or keep.