From 2623ded13684de4af7de4595cad1063eecb0a0a1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miguel=20=C3=81ngel?= Date: Mon, 16 Nov 2026 17:20:55 +0000 Subject: [PATCH] fix(cli): a render that fails says why, even on a crash or a silent exit (#7957) --- packages/cli/src/cli.lifecycle.test.ts | 99 ++++++++++++++++++++++++ packages/cli/src/cli.ts | 45 ++++++++++- packages/cli/src/cliDispatchTestUtils.ts | 3 +- packages/cli/src/commands/render.ts | 2 + packages/cli/src/telemetry/events.ts | 2 +- packages/cli/src/utils/commandResult.ts | 10 +++ packages/cli/src/utils/jsonError.ts | 2 + 7 files changed, 158 insertions(+), 5 deletions(-) diff --git a/packages/cli/src/cli.lifecycle.test.ts b/packages/cli/src/cli.lifecycle.test.ts index 8f0294c2b3..167ca3aa7e 100644 --- a/packages/cli/src/cli.lifecycle.test.ts +++ b/packages/cli/src/cli.lifecycle.test.ts @@ -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[]> { return sent; } +function mockRenderCommand(run: () => void | Promise): 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): string { + return said.mock.calls.map((args: unknown[]) => args.join(" ")).join("\n"); +} + function mockInitCommand(run: () => void | Promise): void { vi.doMock("./commands/init.js", () => ({ default: { diff --git a/packages/cli/src/cli.ts b/packages/cli/src/cli.ts index 4151666752..4088f5ddbc 100644 --- a/packages/cli/src/cli.ts +++ b/packages/cli/src/cli.ts @@ -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 { 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 { 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; diff --git a/packages/cli/src/cliDispatchTestUtils.ts b/packages/cli/src/cliDispatchTestUtils.ts index fbfe43d05d..35969334a8 100644 --- a/packages/cli/src/cliDispatchTestUtils.ts +++ b/packages/cli/src/cliDispatchTestUtils.ts @@ -8,6 +8,7 @@ export function mockTelemetry( flushSync?: ReturnType; trackCommandResult?: ReturnType; trackCommandFailure?: ReturnType; + trackCliError?: ReturnType; } = {}, ): 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(), })); diff --git a/packages/cli/src/commands/render.ts b/packages/cli/src/commands/render.ts index 5b6c3251be..00ee1cd983 100644 --- a/packages/cli/src/commands/render.ts +++ b/packages/cli/src/commands/render.ts @@ -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; diff --git a/packages/cli/src/telemetry/events.ts b/packages/cli/src/telemetry/events.ts index 3fa1b68eb7..e280c962f7 100644 --- a/packages/cli/src/telemetry/events.ts +++ b/packages/cli/src/telemetry/events.ts @@ -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; diff --git a/packages/cli/src/utils/commandResult.ts b/packages/cli/src/utils/commandResult.ts index 8f7ff1b8c9..50e4910433 100644 --- a/packages/cli/src/utils/commandResult.ts +++ b/packages/cli/src/utils/commandResult.ts @@ -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, diff --git a/packages/cli/src/utils/jsonError.ts b/packages/cli/src/utils/jsonError.ts index 616143daab..b21f2d678d 100644 --- a/packages/cli/src/utils/jsonError.ts +++ b/packages/cli/src/utils/jsonError.ts @@ -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++;