Fix CLI formatting for empty Blueprint error messages

[chubes4]

What?

Preserves diagnostic details when the CLI catches an Error with an empty top-level message but a populated cause chain.

This fixes wp-playground-cli run-blueprint printing only:

Error:

for Blueprint runPHP fatals whose PHP failure details are available through the nested cause.

Fixes #3614.

Why?

The CLI describeError() helper returned error.message immediately for Error instances. When that message was empty, it never inspected cause, even though the Blueprint/PHP failure details were present there.

Evidence

A Homeboy rig was added first to reproduce and measure this path:

• Repro harness: feat(playground): add CLI diagnostic rig chubes4/homeboy-rigs#107
• Baseline run: 79d1d8c6-0bb5-4abb-8e18-5467e708cff2
• Candidate run: 52652822-759d-438c-a56e-8d4b6605dc33

Baseline metrics:

control_exit_code=0
fatal_exit_code=1
fatal_blank_error=1
fatal_has_php_diagnostic=0

Candidate metrics:

control_exit_code=0
fatal_exit_code=1
fatal_blank_error=0
fatal_has_php_diagnostic=1

Candidate output includes the PHP fatal:

Error: Error — caused by: Error when executing the blueprint step #1: PHP.run() failed with exit code 255.

=== Stdout ===
Fatal error: Uncaught Error: Call to undefined function playground_cli_missing_probe_function()

Testing Instructions

npx nx test-playground-cli playground-cli --testNamePattern="describeError"

Also verified with the Homeboy rig:

homeboy bench --force-hot \
  --rig playground-cli-diagnostics \
  --path /Users/chubes/Developer/wordpress-playground@improve-runphp-error-output \
  --scenario playground-cli-runphp-errors \
  --iterations 1 \
  --shared-state /var/folders/lr/c_cmmt7s0592m4njz99v5yb40000gn/T/opencode/playground-cli-final-confirm \
  --output /var/folders/lr/c_cmmt7s0592m4njz99v5yb40000gn/T/opencode/playground-cli-final-confirm/bench-output.json

AI assistance

• AI assistance: Yes
• Tool(s): OpenCode (GPT-5.5)
• Used for: Diagnosed the CLI formatter issue using the Homeboy repro rig, implemented the minimal formatter fix, added focused test coverage, and ran verification.

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Updates the Playground CLI error formatter to preserve diagnostic details when top-level Error.message is empty but useful information exists in a nested cause chain (fixing blank Error: output for Blueprint runPHP fatals).

Changes:

• Exported and enhanced describeError() to fall back to inspecting cause (and other object fields) when Error.message is empty.
• Added a focused unit test to assert cause is used when the top-level message is empty.
• Minor formatting cleanup in an existing test block.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
packages/playground/cli/src/run-cli.ts	Improves describeError() formatting by traversing object fields (including cause) when needed; exports helper for testing.
packages/playground/cli/tests/run-cli.spec.ts	Adds regression test for empty-message Error with populated cause chain.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[chubes4]

Addressed Copilot review feedback in the latest push.

Changes made:

• Added WeakSet cycle detection and a max cause-depth guard for recursive error formatting.
• Suppressed the generic empty-message Error name when falling back to a cause chain, so output is cleaner.
• Added regression coverage for a self-referential Error.cause chain.

Re-verified:

• Focused CLI formatter test passed: npx nx test-playground-cli playground-cli --testNamePattern="describeError"
• Homeboy rig run 5991a4eb-fa6a-4c6c-b400-97e4b42d2d3c passed with fatal_blank_error=0 and fatal_has_php_diagnostic=1.

[mho22]

@chubes4 I am deeply sorry, I completely missed this assignment. I will review it now.

[mho22]

Thanks for the contribution ! I added some suggestions.

[chubes4]

No worries at all for the delay, thanks for reviewing.

I pushed an update addressing your comments:

• moved describeError out of run-cli.ts into @php-wasm/universal and export it there
• preserved suppressGenericErrorName through recursive cause formatting
• ordered local fields before nested cause details
• simplified the CLI catch path to rely on the shared formatter and added regression coverage for the nested/ordered cases

Verification: nx typecheck php-wasm-universal and nx typecheck playground-cli pass. I also ran direct formatter assertions. The focused test-playground-cli --testNamePattern=describeError target is currently blocked during suite collection by the existing isomorphic-git/src/models/GitPktLine.js deep-import resolution issue in storage.

[mho22]

Thank you @chubes4 ! A few structural points on this revision:

• There's already packages/php-wasm/universal/src/lib/error-reporting.ts covering the same surface. I'd fold describeError into that file rather than introducing a parallel error-formatting.ts.

• With the first suggestion, the test should then belong in packages/php-wasm/universal/src/test/error-reporting.spec.ts next to the other universal specs.

What do you think ?

[chubes4]

Addressed the latest structural review feedback.\n\nChanges made:\n- folded describeError into the existing packages/php-wasm/universal/src/lib/error-reporting.ts module\n- removed the parallel error-formatting.ts module\n- moved the formatter regression coverage to packages/php-wasm/universal/src/test/error-reporting.spec.ts\n- kept the CLI consuming describeError through @php-wasm/universal\n\nVerification:\n- npx nx typecheck php-wasm-universal\n- npx nx typecheck playground-cli\n- npx nx test:vite php-wasm-universal --testNamePattern=describeError\n- npx nx lint php-wasm-universal\n- npx nx lint playground-cli

[mho22]

Nothing to add. Thanks a lot @chubes4 for this contribution.

[chubes4]

@mho22 Thank you!