feat(command): add CommandSpec::raw_output for verbatim stdout commands

[jpage-godaddy]

Summary

• Adds CommandSpec::raw_output(true) so a command's successful string result prints byte-for-byte to stdout, bypassing --output/--json/--human/--toon and the --fields/--filter/--expr pipeline entirely.
• --output/--fields/--filter/--expr are hidden from a raw_output command's own --help (still parse harmlessly if passed anyway — same convention as --dry-run on non-mutating commands).
• Guards against pairing raw_output with streaming commands or .with_pagination(...) (both debug_assert!).
• Guarantees exactly one trailing newline without doubling one the handler's string already had (e.g. text read from a file) — caught in review, fixed with a regression test.

Fixes the case where a command whose only correct output is verbatim text (e.g. a GraphQL SDL dump) gets JSON-escaped instead of raw text when piped to a file — see DEVEX-993.

Test plan

• cargo fmt --all --check
• cargo clippy --all-targets -- -D warnings
• RUSTDOCFLAGS='-D warnings' cargo doc --no-deps
• cargo rustdoc --lib -- -W missing-docs (zero)
• cargo test --all-targets (new coverage in tests/raw_output.rs, plus new panic-guard tests in tests/foundation.rs and a human.rs unit test)
• cargo test --doc

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR introduces CommandSpec::raw_output(true) to support commands whose only correct output is verbatim text, bypassing the normal output envelope/pipeline and hiding now-irrelevant formatting flags from the command’s help.

Changes:

• Add CommandSpec::raw_output(true) and plumb raw_output through command registration into middleware rendering.
• Update clap help/flag behavior so --output/--fields/--filter/--expr are hidden (but still accepted) for raw-output commands.
• Add end-to-end and guardrail tests covering raw output rendering, help visibility, and invalid raw_output+pagination/streaming combinations.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
cli-engine/tests/raw_output.rs	Adds end-to-end tests asserting raw-output rendering and help flag hiding behavior.
cli-engine/tests/foundation.rs	Updates middleware request helpers and adds panic-guard tests for unsupported raw_output combinations.
cli-engine/src/output/human.rs	Adds a unit test documenting plain-string human formatting behavior relevant to raw text output expectations.
cli-engine/src/middleware.rs	Implements the raw-output render bypass in the middleware render path.
cli-engine/src/command.rs	Adds the raw_output flag to CommandSpec plus debug-assert guards for streaming constructors.
cli-engine/src/cli.rs	Hides irrelevant output/pipeline flags for raw-output commands and asserts pagination incompatibility at clap-tree build time.
cli-engine/docs/concepts.md	Documents the raw-output concept and intended behavior.
AGENTS.md	Updates the command authoring checklist to include raw_output(true) guidance.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated no new comments.

Suppressed comments (2)

cli-engine/src/middleware.rs:1018

• The raw-output renderer claims to guarantee exactly one trailing newline, but strip_suffix('\n') only removes a single newline. If the handler returns text ending in multiple newlines (e.g. a blob with a trailing blank line), the output will still end with multiple newlines, violating that contract.

                    let body = text.strip_suffix('\n').unwrap_or(text);

cli-engine/src/output/human.rs:1167

• This test comment says raw_output relies on format_plain_value, but the raw_output path renders directly from Value::String in middleware (it doesn't go through the human formatter). Updating the comment will avoid future confusion about the dependency.

        // No quoting/escaping — the exact convention `raw_output` bypass
        // relies on to render a `CommandResult` string byte-for-byte.