fix(cli): preserve empty error causes

Author: chubes4

packages/playground/cli/src/run-cli.ts

@@ -798,38 +798,78 @@ export async function parseOptionsAndRunCLI(argsToParse: string[]) {
  * plain objects (which lose their Error prototype during worker thread
  * transfer), and arbitrary values.
  */
-function describeError(error: unknown): string {
+export function describeError(
+	error: unknown,
+	seen = new WeakSet<object>(),
+	depth = 0
+): string {
+	if (depth > 10) {
+		return '[Max error cause depth exceeded]';
+	}
 	if (error instanceof Error) {
-		return error.message;
+		return (
+			error.message ||
+			describeErrorObject(error, seen, depth, {
+				suppressGenericErrorName: true,
+			})
+		);
 	}
 	if (error && typeof error === 'object') {
-		// Comlink-serialized errors arrive as plain objects like
-		// { name: 'ErrnoError', errno: 20 } with no .message.
-		const parts = [];
-		const obj = error as Record<string, unknown>;
-		if (obj['name']) {
-			parts.push(String(obj['name']));
-		}
-		if (obj['message']) {
-			parts.push(String(obj['message']));
-		}
-		if (obj['errno'] !== undefined) {
-			parts.push(`errno: ${obj['errno']}`);
-		}
-		if (parts.length > 0) {
-			return parts.join(' — ');
-		}
-		// Last resort: JSON-serialize the object so we at least see
-		// what fields it has.
-		try {
-			return JSON.stringify(error);
-		} catch {
-			return String(error);
-		}
+		return describeErrorObject(error, seen, depth);
 	}
 	return String(error);
 }
 
+type ErrorLikeObject = object & {
+	name?: unknown;
+	message?: unknown;
+	cause?: unknown;
+	errno?: unknown;
+};
+
+function describeErrorObject(
+	error: ErrorLikeObject,
+	seen: WeakSet<object>,
+	depth: number,
+	options: { suppressGenericErrorName?: boolean } = {}
+): string {
+	if (seen.has(error)) {
+		return '[Circular error cause]';
+	}
+	seen.add(error);
+
+	// Comlink-serialized errors arrive as plain objects like
+	// { name: 'ErrnoError', errno: 20 } with no .message.
+	const parts = [];
+	if (
+		error['name'] &&
+		!(options.suppressGenericErrorName && error['name'] === 'Error')
+	) {
+		parts.push(String(error['name']));
+	}
+	if (error['message']) {
+		parts.push(String(error['message']));
+	}
+	if (error['cause']) {
+		parts.push(
+			`caused by: ${describeError(error['cause'], seen, depth + 1)}`
+		);
+	}
+	if (error['errno'] !== undefined) {
+		parts.push(`errno: ${error['errno']}`);
+	}
+	if (parts.length > 0) {
+		return parts.join(' — ');
+	}
+	// Last resort: JSON-serialize the object so we at least see
+	// what fields it has.
+	try {
+		return JSON.stringify(error);
+	} catch {
+		return String(error);
+	}
+}
+
 function getMountForVfsPath(
 	mounts: Mount[],
 	vfsPath: string

packages/playground/cli/tests/run-cli.spec.ts

@@ -6,6 +6,7 @@ import {
 	parseOptionsAndRunCLI,
 	internalsKeyForTesting,
 	resolveWorkerCount,
+	describeError,
 } from '../src/run-cli';
 import type { RunCLIArgs, RunCLIServer } from '../src/run-cli';
 import type { MockInstance } from 'vitest';
@@ -1199,6 +1200,29 @@ describe('start command', () => {
 	}, 180000);
 });
 
+describe('describeError', () => {
+	test('falls back to Error cause when message is empty', () => {
+		const error = new Error('', {
+			cause: new Error(
+				'Error when executing the blueprint step #1: PHP.run() failed with exit code 255.'
+			),
+		});
+
+		const description = describeError(error);
+		expect(description).toContain(
+			'Error when executing the blueprint step #1'
+		);
+		expect(description.startsWith('Error —')).toBe(false);
+	});
+
+	test('terminates circular cause chains', () => {
+		const error = new Error('');
+		error.cause = error;
+
+		expect(describeError(error)).toContain('[Circular error cause]');
+	});
+});
+
 describe('php command', () => {
 	class ProcessExitCalled extends Error {
 		exitCode: number;