feat(output): restore the { ok, command, result, next_actions } envelope (DEVX-543)#113
Open
smukherjee-godaddy wants to merge 1 commit into
Open
Conversation
…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>
Collaborator
There was a problem hiding this comment.
This skill is for the TypeScript CLI; we're not changing that, so we don't need this to be updated.
jpage-godaddy
requested changes
Jul 16, 2026
jpage-godaddy
left a comment
Collaborator
There was a problem hiding this comment.
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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/.resultwas broken, and error envelopes went to stderr.Fix
Wrap cli-engine output in the public envelope at the binary boundary:
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 thecommandfrom argv by walking the clap tree, emitting only recognized subcommand names, never argument values, so a secret passed as an argument cannot leak into thecommandfield.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.application deploy) writes NDJSON straight to stdout via cli-engine (emptyrendered) 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.{ ok: false, command, error, next_actions }with a non-zero exit.--help/--versionstay plain text;deploystreaming is unaffected.Testing
output_envelope): success / failure / missing-next_actions/ non-JSON pass-through, plus 4command_pathcases including a secret-safety test (--invalid secret-valueleaf is never echoed).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:
warnings(currently dropped) before agents build on the shape — highest-value follow-up.application deploystreaming-skip with a structural signal.fix:recovery hint (dropped); malformed-error→stdout edge rolls into DEVX-542;--output/--json/--human/--toondocumentation is W5 scope.Context
Track A output contract. Composes with #97 (DEVX-546
api callshape) and precedes DEVX-544 (streaming terminal event).