Skip to content

feat(output): restore the { ok, command, result, next_actions } envelope (DEVX-543)#113

Open
smukherjee-godaddy wants to merge 1 commit into
godaddy:rust-portfrom
smukherjee-godaddy:DEVX-543-output-envelope
Open

feat(output): restore the { ok, command, result, next_actions } envelope (DEVX-543)#113
smukherjee-godaddy wants to merge 1 commit into
godaddy:rust-portfrom
smukherjee-godaddy:DEVX-543-output-envelope

Conversation

@smukherjee-godaddy

Copy link
Copy Markdown
Contributor

Problem

The Rust CLI emitted cli-engine's native envelope — { data, metadata, error, warnings, next_actions } — instead of the documented GoDaddy public contract { ok, command, result, next_actions }. Every consumer (scripts, CI, agents, docs, skills) that checks .ok / .result was broken, and error envelopes went to stderr.

Fix

Wrap cli-engine output in the public envelope at the binary boundary:

success -> { ok: true,  command, result, next_actions }
failure -> { ok: false, command, error: { code, message }, next_actions }
  • output_envelope::adapt() — parses the cli-engine JSON render and rewraps it. Non-JSON output (--help, --version, --human, --toon) fails to parse and passes through unchanged.
  • output_envelope::command_path() — derives the command from argv by walking the clap tree, emitting only recognized subcommand names, never argument values, so a secret passed as an argument cannot leak into the command field.
  • main.rs — captures the engine render, adapts it, and writes the public envelope to stdout for both success and failure, preserving the non-zero exit code on failure.
  • Streaming (application deploy) writes NDJSON straight to stdout via cli-engine (empty rendered) and is intentionally not adapted; its terminal-event contract is tracked separately (DEVX-544).

Impact

  • gddy <cmd> again emits { ok, command, result, next_actions } on stdout.
  • Errors are on stdout as { ok: false, command, error, next_actions } with a non-zero exit.
  • --help / --version stay plain text; deploy streaming is unaffected.

Testing

  • Unit (output_envelope): success / failure / missing-next_actions / non-JSON pass-through, plus 4 command_path cases including a secret-safety test (--invalid secret-value leaf is never echoed).
  • Integration (tests/output_contract.rs, real binary): stdout envelope shape, error-on-stdout with exit code, plain --help / --version.
  • cargo test (13 pass) / cargo clippy --all-targets -- -D warnings / cargo fmt --check — all clean.

Reviewed / scoped follow-ups (deferred, not blocking)

Tech-lead review: ship now, no fix-now items. Follow-ups filed separately:

  • Decide fate of cli-engine warnings (currently dropped) before agents build on the shape — highest-value follow-up.
  • Replace the literal application deploy streaming-skip with a structural signal.
  • fix: recovery hint (dropped); malformed-error→stdout edge rolls into DEVX-542; --output/--json/--human/--toon documentation is W5 scope.

Context

Track A output contract. Composes with #97 (DEVX-546 api call shape) and precedes DEVX-544 (streaming terminal event).

…nvelope (DEVX-543)

Restore the documented GoDaddy public JSON contract on top of cli-engine's native
{ data, metadata, error, warnings, next_actions } shape:

  success -> { ok: true, command, result, next_actions }
  failure -> { ok: false, command, error: { code, message }, next_actions }

- output_envelope::adapt() wraps a parsed cli-engine JSON render into the public
  envelope; non-JSON output (help/version/human/toon) passes through unchanged.
- output_envelope::command_path() derives the command from argv using the clap
  tree, emitting only recognized subcommand names — never argument values — so a
  secret passed as an arg cannot leak into the `command` field.
- main.rs captures the engine render, adapts it, and writes the public envelope to
  stdout (errors included, with a non-zero exit code preserved).
- Streaming commands (application deploy) write NDJSON straight to stdout via
  cli-engine and are intentionally not adapted; their terminal-event contract is
  tracked separately (DEVX-544).
- Tests: adapt() success/failure/missing-next_actions/non-JSON + command_path
  secret-safety cases; integration tests over the real binary for stdout envelope,
  error-on-stdout with exit code, and plain help/version.
- Docs (README, SKILL) updated to the current contract and limitations.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This skill is for the TypeScript CLI; we're not changing that, so we don't need this to be updated.

@jpage-godaddy jpage-godaddy left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we need to discuss this with @wcole1-godaddy. I'm not sure this is relevant/accurate. The output shape shifted when we merged the output envelope behavior for gdx and gddy, but I don't think the JSON shape being exact is a hard requirement. Hold on this.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants