Structured output & CLI API hardening (output + errors + --describe)

[aristidesstaffieri]

Part of the Improve Agent UX for Wallets epic.

Summary

Harden the CLI API so an agent/human can parse any command's result and chain commands together without scraping plain text. Three facets, tracked as one task: a global structured-output flag, a structured error catalog, and a --describe machine-readable schema.

1. Structured output

New global flag:

output=json|default

• default — today's default (plain text for most commands, a few existing JSON exceptions).
• json — an object with predictable keys representing the same data plus enriched output in some cases (e.g. errors paired with a resolution).

Example (ok):

{ "status": "ok", "result": "9999999500", "error": null }

Example (error):

{
  "status": "error",
  "result": null,
  "error": {
    "code": "tx_simulation_failed",
    "domain": "tx",
    "message": "host invocation failed: Error(Contract, #2)",
    "details": {
      "contract_id": "C...",
      "error_code": 2,
      "error_name": "InsufficientBalance",
      "diagnostic_events": ["..."]
    }
  }
}

2. Structured errors

commands return an object with a consistent set of keys.
errors add context along with raw error details to aid users/agents towards remediation of the error.

3. --describe

A projection of the command spec: a machine-readable schema for a command or the tree (args, output schema, errors[], examples). Backed by a command-spec source file feeding the parser / --help / --describe generator.

Build on existing OutputFormat patterns (events.rs, fee_stats.rs, ledger/fetch.rs) and print.rs.

Acceptance criteria

• The spec's example envelopes (ok-result and error-with-remediation) reproduce.
• --describe emits args / output / errors[] / examples.
• commands emit parseable JSON under output=json.

[janewang]

@aristidesstaffieri @oceans404 @fnando Does it make sense only for machine-facing CLI API, or should it be for humans too?

[aristidesstaffieri]

@aristidesstaffieri @oceans404 @fnando Does it make sense only for machine-facing CLI API, or should it be for humans too?

the summary just focuses on the improvement in a parsable format, but it is useful for humans also, I will update the text.