Skip to content

Define versioned JSON success and error envelopes #34

Description

@delaudio

Parent epic: #31

Problem

Machine consumers need a stable contract that is independent of terminal formatting, colors, and prose changes.

Scope

Define the common protocol used by every structured Hum command.

A successful response should expose at least:

  • schemaVersion
  • command identity
  • project and template context when applicable
  • a command-specific data payload

A structured failure should expose at least:

  • schemaVersion
  • a stable error code
  • a safe human-readable message
  • optional structured details
  • the documented process exit code

Acceptance criteria

  • Structured output never contains ANSI control sequences.
  • stdout contains only the structured payload in structured mode.
  • diagnostics that are not part of the payload go to stderr.
  • Error codes and exit-code mappings are documented and tested.
  • Serialization is deterministic enough for contract fixtures.
  • Secret values, provider output, tokens, and raw environment maps are excluded.
  • Existing human-readable commands remain backward compatible.
  • Shared Rust types/helpers prevent each command from inventing its own envelope.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions