Module json_envelope 

Canonical JSON envelope for harn CLI commands.

Every --json mode returns a JsonEnvelope<T> — a versioned wrapper that exposes schemaVersion, ok, and either data or error. Soft signals attach as warnings so ok: true stays stable as long as the command succeeds.

Schema versions are per-command and monotonically increasing. catalog returns the registry consumed by harn --json-schemas. New commands extend the catalog (and bump their own JsonOutput::SCHEMA_VERSION) when their JSON shape changes in a way agents need to detect.

See epic #1753 (--json everywhere) for the broader contract.

Structs

JsonEnvelope

Versioned wrapper for every --json CLI output. All five fields are always serialized so consumers can rely on a flat shape: missing payloads surface as null and the empty warnings array is [] rather than absent.

JsonError

JsonWarning

SchemaEntry

One row of the harn --json-schemas catalog. schema_json is inline when small; richer schemas live behind a future schema_url field documented per-command.

Constants

CATALOG_SCHEMA_VERSION

Schema version of the harn --json-schemas catalog itself. Bump when the shape of SchemaEntry or the catalog envelope changes.

Traits

JsonOutput

Implemented by every CLI command that exposes a --json mode. The associated SCHEMA_VERSION is also surfaced in catalog so agents can negotiate per-command compatibility without parsing every payload.

Functions

catalog

Static catalog of commands that already emit a stable JSON shape.

to_string_pretty

Encode an envelope as JSON. Uses pretty form so humans tailing the terminal can still read it; agents jq-pipe either form.