fix(cli): a render that fails says why, even on a crash or a silent exit (#7957)

This commit is contained in:
Miguel Ángel
2026-11-16 17:20:55 +00:00
committed by GitHub
parent c77cd301c8
commit 2623ded136
7 changed files with 158 additions and 5 deletions
+99
View File
@@ -322,6 +322,94 @@ describe("CLI lifecycle", () => {
}
});
// fails without the fix: a program driving the CLI read exit 1 with no words, so its reports named a routine line
// ("Browser: env") as the cause.
it("says what crashed before the command delivered, then exits 1", async () => {
const exitSpy = vi.spyOn(process, "exit").mockImplementation((() => undefined) as never);
const said = vi.spyOn(console, "error").mockImplementation(() => {});
const priorListeners = process.listeners("uncaughtException");
process.removeAllListeners("uncaughtException");
try {
mockInitCommand(() => {
process.emit("uncaughtException", new Error("EBADF: bad file descriptor, read"));
});
mockTelemetry({ trackCommandResult: vi.fn() });
process.argv = ["node", "cli.ts", "init"];
await import("./cli.js");
expect(saidOnStderr(said)).toContain("Error: EBADF: bad file descriptor, read");
expect(exitSpy).toHaveBeenCalledWith(1);
} finally {
process.removeAllListeners("uncaughtException");
for (const listener of priorListeners) process.on("uncaughtException", listener);
said.mockRestore();
exitSpy.mockRestore();
}
});
it("says what an unhandled rejection was before the command delivered", async () => {
const said = vi.spyOn(console, "error").mockImplementation(() => {});
const priorListeners = process.listeners("unhandledRejection");
process.removeAllListeners("unhandledRejection");
try {
mockInitCommand(() => {
process.emit(
"unhandledRejection",
new Error("browser process would not stop"),
Promise.resolve(),
);
});
mockTelemetry({ trackCommandResult: vi.fn() });
process.argv = ["node", "cli.ts", "init"];
await import("./cli.js");
expect(saidOnStderr(said)).toContain("Error: browser process would not stop");
} finally {
process.removeAllListeners("unhandledRejection");
for (const listener of priorListeners) process.on("unhandledRejection", listener);
said.mockRestore();
}
});
it("a render ending non-zero with no failure shown says so, and reports where the failure was set", async () => {
const said = vi.spyOn(console, "error").mockImplementation(() => {});
const trackCliError = vi.fn();
try {
mockRenderCommand(async () => {
const { setCommandExitCode } = await import("./utils/commandResult.js");
setCommandExitCode(1);
});
mockTelemetry({ trackCommandResult: vi.fn(), trackCliError });
process.argv = ["node", "cli.ts", "render"];
await import("./cli.js");
expect(saidOnStderr(said)).toContain("The command ended with code 1 without saying why");
expect(trackCliError).toHaveBeenCalledWith(
expect.objectContaining({
kind: "silent_exit",
stack_trace: expect.stringContaining("cli.lifecycle.test.ts"),
}),
);
} finally {
said.mockRestore();
}
});
it("a command that answers with a non-zero code is not called silent", async () => {
const said = vi.spyOn(console, "error").mockImplementation(() => {});
const trackCliError = vi.fn();
try {
mockInitCommand(async () => {
const { setCommandExitCode } = await import("./utils/commandResult.js");
setCommandExitCode(1);
});
mockTelemetry({ trackCommandResult: vi.fn(), trackCliError });
process.argv = ["node", "cli.ts", "init"];
await import("./cli.js");
expect(saidOnStderr(said)).not.toContain("without saying why");
expect(trackCliError).not.toHaveBeenCalled();
} finally {
said.mockRestore();
}
});
it("exits 0 when a late uncaught exception follows a command that already delivered", async () => {
const exitSpy = vi.spyOn(process, "exit").mockImplementation((() => undefined) as never);
const priorListeners = process.listeners("uncaughtException");
@@ -470,6 +558,17 @@ async function runCli(args: string[]): Promise<Record<string, unknown>[]> {
return sent;
}
function mockRenderCommand(run: () => void | Promise<void>): void {
vi.doMock("./commands/render.js", () => ({
default: { meta: { name: "render" }, args: {}, run },
}));
}
/** Everything the run wrote through console.error, colors and all, as one text. */
function saidOnStderr(said: ReturnType<typeof vi.spyOn>): string {
return said.mock.calls.map((args: unknown[]) => args.join(" ")).join("\n");
}
function mockInitCommand(run: () => void | Promise<void>): void {
vi.doMock("./commands/init.js", () => ({
default: {
+42 -3
View File
@@ -13,6 +13,8 @@
// arrives after the render artifact was validated is the normal agent-pipe
// teardown and must stay success:true (see handleStreamEpipe).
let commandFailed = false;
// A cli_error went out for this run: its failure is already named.
let errorReported = false;
for (const stream of [process.stdout, process.stderr]) {
stream.on("error", (err) => {
@@ -90,7 +92,8 @@ import {
} from "./utils/render-success-state.js";
import { resolveCommandUsage, type ResolvedCommandUsage } from "./utils/commandUsageResolution.js";
import { closestMatch, closestNames, commandRedirect, fileHint } from "./utils/didYouMean.js";
import { jsonErrorBody, watchOutput, writeJsonFailure } from "./utils/jsonError.js";
import { errorBox } from "./ui/format.js";
import { failureShown, jsonErrorBody, watchOutput, writeJsonFailure } from "./utils/jsonError.js";
import { isDevMode } from "./utils/env.js";
import {
CliResultSignal,
@@ -99,6 +102,7 @@ import {
USAGE_EXIT_CODE,
consumeCommandResult,
endProcess,
failureOrigin,
outputWritten,
registerRootExitCodeSanitizer,
registerRootExitRequester,
@@ -254,7 +258,7 @@ let _trackCliError:
error_message: string;
stack_trace?: string;
command?: string;
kind: "uncaught_exception" | "unhandled_rejection" | "command_error";
kind: "uncaught_exception" | "unhandled_rejection" | "command_error" | "silent_exit";
}) => void)
| undefined;
let _trackCommandResult:
@@ -372,6 +376,9 @@ async function finalizeCli(result: CommandResult): Promise<void> {
if (exitCode === 0) markCommandDelivered();
commandFailed ||= exitCode !== 0;
await telemetryReady.catch(() => {});
// Render shows every failure it knows (errorBox); lint, diff and the like end non-zero as their answer.
if (command === "render" && exitCode !== 0 && !errorReported && !failureShown())
sayNoMessage(exitCode);
_trackCommandResult?.({
command,
success: exitCode === 0 && commandSucceededForTelemetry(),
@@ -441,7 +448,11 @@ process.on(
// Report a CLI error event to telemetry. Extracted from the process-error
// handlers so their bodies stay simple linear branches (see fallow CRAP
// scoring — arrow handlers with inline telemetry calls tip past threshold).
function emitCliErrorEvent(kind: "uncaught_exception" | "unhandled_rejection", error: Error): void {
function emitCliErrorEvent(
kind: "uncaught_exception" | "unhandled_rejection" | "silent_exit",
error: Error,
): void {
errorReported = true;
_trackCliError?.({
error_name: error.name,
error_message: error.message,
@@ -503,6 +514,31 @@ function commandSucceededForTelemetry(): boolean {
return !commandFailed || isRenderSucceeded();
}
// A crash before the command delivered says what it was: a program driving the CLI otherwise gets
// an exit 1 with no words at all.
function sayCrash(error: Error): void {
const words = [`${error.name}: ${error.message}`, firstFrameOf(error.stack)];
errorBox("The command stopped on an unexpected error", words.filter(Boolean).join("\n"));
}
/** The first caller line of a stack, past the Error's own line and the result bookkeeping that recorded it. */
const firstFrameOf = (stack: string | undefined) =>
stack
?.split("\n")
.map((line) => line.trim())
.find((line) => line.startsWith("at ") && !line.includes("commandResult"));
// A run ending non-zero that showed and reported no failure (errorBox records what it shows): say so, and send the
// stack that first set the failing result (commandResult.ts failureOrigin), since the exit code alone names nothing.
function sayNoMessage(exitCode: number): void {
const origin = failureOrigin();
errorBox(`The command ended with code ${exitCode} without saying why`, firstFrameOf(origin));
emitCliErrorEvent(
"silent_exit",
Object.assign(new Error(`exit ${exitCode} with no failure shown`), { stack: origin }),
);
}
// Terminate the process after a genuine CLI failure — mark commandFailed,
// emit telemetry, flush, exit(1). Same rationale as above: keeps the arrow
// handler linear so fallow CRAP stays under threshold.
@@ -511,6 +547,7 @@ function exitAfterCliFailure(
error: Error,
): never {
commandFailed = true;
sayCrash(error);
emitCliErrorEvent(kind, error);
_flushSync?.();
process.exit(1);
@@ -545,6 +582,7 @@ process.on("unhandledRejection", (reason) => {
}
commandFailed = true;
process.exitCode = 1;
sayCrash(error);
emitCliErrorEvent("unhandled_rejection", error);
});
@@ -660,6 +698,7 @@ async function executeCli(): Promise<void> {
result = commandResultForError(error);
if (!(error instanceof CliResultSignal)) {
commandFailed = true;
errorReported = true;
await reportCommandFailure(command, error);
const typed = error instanceof CliUsageError || error instanceof CliRuntimeError;
const usage = error instanceof CliUsageError && !error.result.presented;
+2 -1
View File
@@ -8,6 +8,7 @@ export function mockTelemetry(
flushSync?: ReturnType<typeof vi.fn>;
trackCommandResult?: ReturnType<typeof vi.fn>;
trackCommandFailure?: ReturnType<typeof vi.fn>;
trackCliError?: ReturnType<typeof vi.fn>;
} = {},
): void {
vi.doMock("./telemetry/index.js", () => ({
@@ -16,7 +17,7 @@ export function mockTelemetry(
incrementCommandCount: vi.fn(),
showTelemetryNotice: vi.fn(),
shouldTrack: () => false,
trackCliError: vi.fn(),
trackCliError: overrides.trackCliError ?? vi.fn(),
trackCommand: vi.fn(),
trackCommandResult: overrides.trackCommandResult ?? vi.fn(),
}));
+2
View File
@@ -149,6 +149,7 @@ import {
runPostRenderStepAsync,
} from "../utils/render-success-state.js";
import type { ProducerLogger, RenderJob, RenderPerfSummary } from "@hyperframes/producer";
import { recordFailure } from "../utils/jsonError.js";
import {
EXTRACT_CACHE_DIR_DISABLED_ALIASES,
sandboxDeniedRemediation,
@@ -510,6 +511,7 @@ export default defineCommand({
const reason = cancellation.signal.reason;
const message = reason instanceof Error ? reason.message : String(reason);
process.stderr.write(`Render cancelled: ${message}\n`);
recordFailure(`Render cancelled: ${message}`);
requestCliExit(1);
}
throw error;
+1 -1
View File
@@ -924,7 +924,7 @@ export function trackCliError(props: {
error_message: string;
stack_trace?: string;
command?: string;
kind: "uncaught_exception" | "unhandled_rejection" | "command_error";
kind: "uncaught_exception" | "unhandled_rejection" | "command_error" | "silent_exit";
/** Low-cardinality figma REST call label (e.g. "images", "files_nodes") —
* which endpoint failed, for FigmaClientError-backed failures only. */
endpoint?: string;
+10
View File
@@ -71,7 +71,15 @@ export function failUsage(exitCode = USAGE_EXIT_CODE): never {
throw new CliUsageError("Invalid command usage", { exitCode, presented: true });
}
let firstFailureStack: string | undefined;
const noteFailure = (exitCode: number) => {
if (exitCode !== 0) firstFailureStack ??= new Error("the run failed here").stack;
};
export const failureOrigin = (): string | undefined => firstFailureStack;
export function finishCommand(exitCode = 0): never {
noteFailure(exitCode);
throw new CliResultSignal({
exitCode,
kind: exitCode === 0 ? "success" : "runtime_error",
@@ -81,6 +89,7 @@ export function finishCommand(exitCode = 0): never {
/** Record a non-fatal result while allowing output/finalizers to complete. */
export function setCommandResult(result: CommandResult): void {
noteFailure(result.exitCode);
if (pendingResult.exitCode !== 0 && result.exitCode === 0) return;
pendingResult = result;
}
@@ -141,6 +150,7 @@ export function endProcess(exitCode: number, host: ProcessEnd): void {
/** Ask cli.ts to finalize telemetry/output and then terminate the process. */
export function requestCliExit(exitCode = 0): void {
noteFailure(exitCode);
if (!rootExitRequester) {
setCommandResult({
exitCode,
+2
View File
@@ -55,6 +55,8 @@ export function recordFailure(message: string, hint?: string): void {
reported = { message, hint };
}
export const failureShown = (): boolean => reported !== undefined;
/** Writes a notice (telemetry disclosure, deprecation, progress) that is never an error message. */
export function asNotice(write: () => void): void {
noticeDepth++;