cli: support JSON with comments in request bodies

[KaustubhOG]

Closes #823.

The problem

The CLI parses request bodies as strict JSON, so a body containing comments fails at argument-parse time with "expected , or }" before any request is sent.

The fix

JsonOf::from_str in z-clients/cli/src/json/mod.rs now strips // line comments and /* */ block comments before parsing, on both the inline-argument and stdin (-) paths.

• Comment markers inside string literals are left untouched.
• Newlines inside comments are preserved, so parse-error line numbers still match the original input.
• Valid JSON is unaffected.
• Eight unit tests cover the edge cases: markers inside strings, escaped quotes, CR/CRLF line endings, error line numbers, and comments acting as token separators between values.

After the fix, a body with // and /* */ comments parses the same as plain JSON and fails only at the network step, since no server is running:

Descriptive examples

With parsing in place, the second commit makes the generated "Example body" help blocks carry each field's OpenAPI description as a trailing comment, which is the motivating example from the issue:

Example body:
{
  "namespace": "some_namespace",
  "ttl_ms": 60000, // Time to live in milliseconds
  "behavior": "upsert",
  "version": 123 // If set, the write only succeeds when the stored version matches this value. Use the `version` field from a prior `get` response.
}

This is a one-line change to codegen/templates/cli/api_resource.rs.jinja; the other 11 changed files are regenerated CLI output. The examples are copy-pasteable: all 56 generated example bodies parse back through the CLI. Multi-line descriptions are collapsed to their first paragraph so a sentence that wraps across source lines is not cut off mid-way.

[svix-jplatte]

Have you looked for libraries that directly support parsing JSONC? I really don't think we should be normalizing JSONC to JSON before parsing, that seems rather brittle.

edit: I've looked at crates.io and none of the options seem obviously the best. Not sure we'd want to depend on any of them, but it also seems a bit awkward to have this bespoke comment stripping algorithm.. I'll ask the rest of the team for input.

[svix-lucho]

I agree with @svix-jplatte. I don't see much value in having comments within the JSON body itself, it can lead to unexpected behavior. Are there any other CLIs that do such a thing? I don't remember having seen something like this elsewhere

[KaustubhOG]

Sorry if this came out of nowhere. I saw #823 and thought it would be a good fix for it. The issue asked for the "Example body" blocks in the CLI help to show what each field means as a comment, and suggested jsonc.org, so I went with that.

Your point about unexpected behavior is a good one though, and you're right that it's not something you see in other CLIs. JSONC is mostly a config file thing.

[svix-jbrown]

I think this implementation is fine (if a bit underspecified in how to handle goofy things like nested block comments)

Personally, I'd vote to have us add support for multiple formats of input (e.g., -i json, -i yaml, -i ron) rather than support JSONC, but I wouldn't have a problem with merging this if folks wanted to.