ux: render nested JSON as readable sub-sections in --human mode

[somanshreddy]

Description

Nested objects and arrays in API responses were rendered as compact JSON strings in --human mode (e.g. {"code":"not_found","message":"Video not found"}), making the output hard to scan.

This PR makes the HumanFormatter context-aware for nested structures:

Key-value mode (get commands) now renders nested data as indented sub-sections:

# Before
Wallet:  {"currency":"usd","remaining_balance":150,"auto_reload":{"enabled":true}}

# After
Wallet:
  Currency:          usd
  Remaining Balance: 150
  Auto Reload:
    Enabled:  true

Table mode (list commands) renders string arrays as comma-separated and flat objects as key=value:

# Before
Events: ["avatar_video.success","avatar_video.fail"]
Error:  {"code":"bad_input","message":"invalid"}

# After
Events: avatar_video.success, avatar_video.fail
Error:  code=bad_input, message=invalid

The approach is fully generic with no per-command special-casing. All 5 nesting types across 8 command groups are handled:

• String arrays (events, tags, supported_api_engines) -> comma-separated
• Flat objects (error {code, message}) -> key=value inline (tables) or indented sub-section (key-value)
• Deep objects (wallet, subscription) -> recursive indented sub-sections
• Arrays of objects (messages, word_timestamps) -> numbered entries with indented fields
• Empty collections -> blank in tables, (none) in key-value mode

Design decisions:

• formatValue (shared single-line formatter) handles table cells. renderKeyValue handles key-value mode separately to allow multi-line rendering.
• isScalarArray/isFlatMap exclude nil values to avoid malformed inline output like , x or key=.
• Recursive depth guard at 5 levels (falls back to compact JSON).
• Multiline strings get continuation-line re-indentation at nested levels.
• formatCell field-name-aware formatting (timestamps, durations) works at all nesting levels.

Testing

• Updated 2 existing tests to match new output format
• Added 12 new test cases covering all nesting types, null handling, nested scalar arrays, nested multiline strings, and nested timestamp/duration formatting
• make test passes (all packages)
• make build succeeds

🤖 Generated with Claude Code

[somanshreddy]

• ux: render nested JSON as readable sub-sections in --human mode #104 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[jrusso1020]

Nice work — clean decomposition, solid edge case handling, and thorough test coverage. The split between formatValue (single-line for tables) and renderNestedKeyValue (multi-line for key-value) is the right abstraction boundary. Null exclusion in isScalarArray/isFlatMap is a subtle but important detail. LGTM.

A few optional items below if you want to polish, none blocking.

---

Nit: Consider a blank line between numbered entries in renderArrayOfObjects

With objects that have 5+ fields, back-to-back entries become a wall of text:

  [1]
    Content:  hello
    Role:     user
  [2]
    Content:  hi
    Role:     model

A blank line between entries (maybe when the object has >2 keys) would improve scannability. Up to you — fine as-is for typical API shapes.

Nit: formatMapInline uses raw keys vs humanizeKey elsewhere

Table mode: code=bad_input, message=invalid
Key-value mode: Code: bad_input

This is clearly intentional for compactness in tables, but a one-line comment on formatMapInline noting the design choice would prevent a future contributor from "fixing" it.

Optional: doc note on vacuous truth for empty slices

isScalarArray([]any{}) and isObjectArray([]any{}) both return true. No functional impact since len(v) == 0 is checked first at every call site, but a brief doc note ("returns true for empty slices") would future-proof the contract if these helpers get reused.

Optional: name the separator width constant

valueIndent := prefix + strings.Repeat(" ", lipgloss.Width(label)+len(":  ")+len(padding))

len(": ") = 3 reads as a magic number. A const kvSeparator = ": " or brief comment would help.

[somanshreddy]

Merge activity

• Apr 14, 10:05 PM UTC: A user started a stack merge that includes this pull request via Graphite.
• Apr 14, 10:05 PM UTC: @somanshreddy merged this pull request with Graphite.