fix(cli): keep --json stdout pure across the query commands

[ako]

Symptoms

Found by an agent-orientation audit on a large app (Evora Factory Management, MPR v1, 140MB). --json output did not parse:

• refs, callers, callees, impact, structure, show, search and mxcli -c "select … from CATALOG.x" --json printed Connected to: …, catalog progress (Loading cached catalog…, and 40+ ✓ Table: N lines on a cold cache), a References to X header and a Found N result(s) count ahead of the payload.
• An empty answer was a sentence ((no references found), (no results)) instead of [].
• context ignored --json and printed markdown.
• search took both --format json and --json, with --format json still leaking progress.
• Found in the sweep: check --format json|sarif wrote its document to stderr, one document per phase, so stdout held only executor chatter. show catalog status and show widgets had no JSON path. Empty show data transformers / import mappings / export mappings printed a sentence. diff --json silently printed a text diff. A cold-cache search -q --format names printed the build's ✓ lines ahead of the names.

Cause

The executor has one writer, ctx.Output, and it carries both the payload and every status line. The mendixlabs#904 fix (progressSink, used by lint/report) works because those commands print their payload themselves, so the executor's writer can be pointed at stderr. For the query commands the executor prints the payload, through the same writer as the chatter. No writer choice at the cmd layer can separate the two, so the split has to happen inside the executor, one line at a time.

Fix

• ExecContext.progress() returns Output in text mode, so interactive output is byte-for-byte unchanged. In JSON mode it returns the diagnostics stream (stderr). Connect, catalog load/build/warnings, catalog-query counts, and the refs/callers/callees/impact headers go through it.
• Coordination with fix(search): warn when the source index was never built #716: this reuses the ExecContext.Diagnostics field and diagnostics() helper exactly as fix(search): warn when the source index was never built #716 adds them (identical hunk, nil means stderr). Whichever PR merges second should see a clean or trivial merge there.
• writeEmptyResult: [] in JSON mode, with the sentence moved to stderr.
• context --json wraps the markdown in {name, type, depth, context}, the same envelope shape as describe --json.
• search: --json is canonical. It is the root flag, and every other query command (refs/callers/callees/impact/context/show/describe/select) already uses it. --format json still works as a deprecated alias (listed as such in --help), and it now sets the executor format, so its output is identical (tested).
• check: structured formats now print one document on stdout that covers every phase. The exit code is unchanged. This moves the stream (stderr → stdout). No in-repo consumer read stderr (checked vscode-mdl, docs, scripts).
• diff / diff-local refuse --json (stderr, exit 2) instead of ignoring it. --json is a root persistent flag, so every subcommand accepts it.
• Under -q, a cold catalog build sends its per-table lines to stderr. They are moved, not dropped, because an 18-minute build needs a sign of life.

Tests + proof

cmd/mxcli/json_output_purity_test.go runs the real main() in a child process (reusing TestRunMainHelper), so stdout and stderr are really separate, os.Exit paths can be observed, and no cobra state leaks between rows:

• TestJSONFlagKeepsStdoutPureJSON: a table of 25 subcommand invocations, including a cold-catalog run and empty results that must be []. The next command that prints through the executor belongs in this table.
• TestJSONFlagErrorsGoToStderr: context/describe of a missing element, a bad catalog table, and diff --json. Each must exit non-zero with nothing non-JSON on stdout.
• TestTextModeKeepsProgressOnStdout: the control. Text mode still shows Connected to:, headers and (no … found) on stdout.
• TestSearchFormatJSONAliasIsAsPureAsJSONFlag, TestCheckStructuredOutputIsOneDocumentOnStdout, TestSearchQuietNamesIsOnlyNamesOnAColdCatalog
• mdl/executor/progress_stream_test.go: unit tests for progress() and writeEmptyResult.

Proof by revert:

• Before the fix, every --json row failed with the reported symptom, and the text control passed.
• With progress() forced to return Output, all 18 then-present --json rows failed, plus the alias and error tests.
• With cmd_check.go reverted, all 5 check rows failed (stdout is not JSON).
• With the quiet build progress pointed back at Output, the names test failed on "✓ Modules: 2".

Evora verification (bin/mxcli <cmd> … | jq . >/dev/null, source-mode catalog)

command	result	exit
mxcli refs -p evora.mpr Encryption.Decrypt --json	jq-ok	0
mxcli refs -p evora.mpr Nope.Nothing --json	jq-ok ([])	0
mxcli callers -p evora.mpr Encryption.Decrypt --json	jq-ok	0
mxcli callers -p evora.mpr Encryption.Decrypt --transitive --json	jq-ok	0
mxcli callees -p evora.mpr MxModelReflection.ACT_ShowMemberPage --json	jq-ok	0
mxcli impact -p evora.mpr MxModelReflection.MxObjectType --json	jq-ok	0
mxcli context -p evora.mpr MxModelReflection.MxObjectType --json	jq-ok	0
mxcli context -p evora.mpr Nope.Nothing --json	error → stderr, stdout empty	1
mxcli search -p evora.mpr Customer --json	jq-ok	0
mxcli search -p evora.mpr Customer --format json	jq-ok	0
mxcli search -p evora.mpr zzqqxxnomatch --json	jq-ok ([])	0
mxcli -p evora.mpr -c "select QualifiedName from CATALOG.microflows limit 5" --json	jq-ok	0
mxcli -p evora.mpr -c "select … where Name = 'zz'" --json	jq-ok ([])	0
mxcli -p evora.mpr -c "show catalog status" --json	jq-ok	0
mxcli -p evora.mpr -c "show catalog tables" --json	jq-ok	0
mxcli show -p evora.mpr modules --json	jq-ok	0
mxcli show -p evora.mpr entities --json	jq-ok	0
mxcli show -p evora.mpr microflows MxModelReflection --json	jq-ok	0
mxcli describe -p evora.mpr entity MxModelReflection.MxObjectType --json	jq-ok	0
mxcli structure -p evora.mpr -d 1 --json	jq-ok	0
mxcli check ok.mdl -p evora.mpr --json	jq-ok	0
mxcli lint -p evora.mpr --json	jq-ok	0
mxcli diff -p evora.mpr ok.mdl --json	refused → stderr	2

Text mode on Evora (mxcli refs … Encryption.Decrypt) still prints Connected to: / Loading cached catalog / References to … on stdout.

Validation

• make build and make lint pass.
• make test: the only failures are the .mpk-fixture tests in cmd/mxcli, mdl/executor, modelsdk/widgets/mpk and sdk/widgets/mpk (open …/*.mpk: no such file). This worktree is a sparse checkout that omits .mpk blobs. I reproduced the same failing set on the unmodified base with these changes set aside, so they are pre-existing and unrelated.

Out of scope / noticed

• The 10,000-line output guard counts pretty-printed JSON lines. On Evora, -c "show widgets" --json writes the complete document and then exits 1 with output line limit exceeded.
• mxcli exec script.mdl --json still mixes mutation messages ("Created entity …") with JSON on stdout.
• The per-statement JSON shape of multi-statement -c runs is a stream of documents (jq accepts it; a single-document parser does not).
• check -p with create association … from System.Nope passes the reference check. This is unrelated and was noticed while writing the test.

Finding appended to .claude/skills/fix-issue/findings/cmd-mxcli.jsonl. One sentence added to docs-wiki/bug-patterns/cli-contract-defects.md.

🤖 Generated with Claude Code