Skip to content

Write HTML. Render video. Built for agents.

fix(cli): preview --background reports a preview that cannot start instead of waiting it out (#5437)

Miguel Ángel6c96ea534434
diff --git a/packages/cli/src/commands/preview.startFailure.test.ts b/packages/cli/src/commands/preview.startFailure.test.ts
new file mode 100644
index 0000000000..94df3fc1c1
--- /dev/null
+++ b/packages/cli/src/commands/preview.startFailure.test.ts
@@ -0,0 +1,41 @@
+import { describe, expect, it, vi } from "vitest";
+import { runEmbeddedMode } from "./preview.js";
+
+const ui = vi.hoisted(() => ({
+ spinner: { start: vi.fn(), stop: vi.fn(), message: vi.fn() },
+ error: vi.fn(),
+}));
+vi.mock("@clack/prompts", async (importOriginal) => {
+ const actual = await importOriginal<typeof import("@clack/prompts")>();
+ return {
+ ...actual,
+ spinner: () => ui.spinner,
+ intro: () => {},
+ log: { ...actual.log, error: ui.error },
+ };
+});
+vi.mock("../server/studioServer.js", () => ({
+ resolveStudioBundle: () => ({ available: true, checkedPaths: [] }),
+ loadPreviewServerBuildSignature: async () => "test",
+ createStudioServer: () => ({
+ app: { fetch: () => new Response() },
+ watcher: { close: vi.fn() },
+ shutdown: vi.fn(),
+ }),
+}));
+vi.mock("../server/portUtils.js", async (importOriginal) => ({
+ ...(await importOriginal<typeof import("../server/portUtils.js")>()),
+ findPortAndServe: async () => {
+ throw new Error("listen EPERM: operation not permitted 127.0.0.1:3056");
+ },
+}));
+
+describe("preview start failure", () => {
+ it("stops the startup spinner so a server that cannot listen lets the process exit", async () => {
+ await runEmbeddedMode("start-failure-project", 3056, { noOpen: true });
+
+ expect(ui.spinner.start).toHaveBeenCalledOnce();
+ expect(ui.spinner.stop).toHaveBeenCalledOnce();
+ expect(ui.error).toHaveBeenCalledWith(expect.stringContaining("listen EPERM"));
+ });
+});
diff --git a/packages/cli/src/commands/preview.ts b/packages/cli/src/commands/preview.ts
index 4e29f45d10..7a22a78f0f 100644
--- a/packages/cli/src/commands/preview.ts
+++ b/packages/cli/src/commands/preview.ts
@@ -1542,7 +1542,7 @@ export async function runLocalStudioMode(
* If an existing HyperFrames server for the same project is detected,
* reuses it instead of starting a new one (unless --force-new is set).
*/
-async function runEmbeddedMode(
+export async function runEmbeddedMode(
dir: string,
startPort: number,
options?: EmbeddedStudioOptions,
@@ -1601,6 +1601,7 @@ async function runEmbeddedMode(
);
} catch (err: unknown) {
watcher.close();
+ if (!options?.json) s.stop(c.error("Could not start studio"));
reportPreviewFailure(
Boolean(options?.json),
"start",
diff --git a/packages/cli/src/commands/previewLifecycle.test.ts b/packages/cli/src/commands/previewLifecycle.test.ts
index 57b1ebfc71..614628d541 100644
--- a/packages/cli/src/commands/previewLifecycle.test.ts
+++ b/packages/cli/src/commands/previewLifecycle.test.ts
@@ -1,4 +1,4 @@
-import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync } from "node:fs";
+import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeSync } from "node:fs";
import { tmpdir } from "node:os";
import { join, resolve } from "node:path";
import { describe, expect, it, onTestFinished, vi } from "vitest";
@@ -682,6 +682,32 @@ describe("background preview lifecycle", () => {
expect(result).toMatchObject({ type: "started", port: 3002, pid: 5432 });
});
+ it("stops waiting when the detached child exits and reports its exit and log", async () => {
+ const stateHome = tempDir("hf-preview-state-");
+ const kill = vi.fn();
+ const scan = vi.fn(async () => []);
+ let onExit: ((code: number | null, signal: string | null) => void) | undefined;
+
+ await expect(
+ startBackgroundPreview(projectDir, 3002, {
+ scan,
+ spawn: (_command, _args, options) => {
+ writeSync(
+ options.stdio[1],
+ "\u001b[?25hError: listen EPERM: operation not permitted 127.0.0.1:3002\n",
+ );
+ return { pid: 4321, unref: vi.fn(), once: (_event, listener) => (onExit = listener) };
+ },
+ sleep: async () => onExit?.(1, null),
+ kill,
+ stateHome,
+ }),
+ ).rejects.toThrow(/exited \(exit code 1\) before it was ready[\s\S]*\nError: listen EPERM/);
+
+ expect(kill).not.toHaveBeenCalled();
+ expect(scan.mock.calls.length).toBeLessThan(5);
+ });
+
it("reaps a detached child that never becomes reachable without recording ownership", async () => {
const stateHome = tempDir("hf-preview-state-");
const kill = vi.fn();
diff --git a/packages/cli/src/commands/previewLifecycle.ts b/packages/cli/src/commands/previewLifecycle.ts
index 9e88cb81a9..37c250496d 100644
--- a/packages/cli/src/commands/previewLifecycle.ts
+++ b/packages/cli/src/commands/previewLifecycle.ts
@@ -13,6 +13,7 @@ import {
} from "node:fs";
import { homedir } from "node:os";
import { dirname, join, resolve } from "node:path";
+import { stripVTControlCharacters } from "node:util";
import {
activeServerOnPort,
MAX_PORT_SCAN,
@@ -46,7 +47,11 @@ export interface PreviewSession {
logPath: string;
}
-type SpawnResult = { pid?: number; unref(): void };
+type SpawnResult = {
+ pid?: number;
+ unref(): void;
+ once?(event: "exit", listener: (code: number | null, signal: string | null) => void): unknown;
+};
type SpawnPreview = (
command: string,
args: string[],
@@ -226,7 +231,12 @@ function spawnDetachedPreview(
projectDir: string,
stateHome: string,
dependencies: LifecycleDependencies,
-): { pid: number; wrapperIdentity: string | undefined; logPath: string } {
+): {
+ pid: number;
+ wrapperIdentity: string | undefined;
+ logPath: string;
+ exitedWith: () => string | null;
+} {
const logPath = previewLogPath(projectDir, stateHome);
mkdirSync(dirname(logPath), { recursive: true });
const logFd = openSync(logPath, "a", 0o600);
@@ -246,11 +256,16 @@ function spawnDetachedPreview(
closeSync(logFd);
}
if (!child.pid) throw new Error("background preview child did not report a PID");
+ let exit: string | null = null;
+ child.once?.("exit", (code, signal) => {
+ exit = signal ? `signal ${signal}` : `exit code ${code}`;
+ });
child.unref();
return {
pid: child.pid,
wrapperIdentity: (dependencies.identity ?? processIdentity)(child.pid) ?? undefined,
logPath,
+ exitedWith: () => exit,
};
}
@@ -547,15 +562,28 @@ export async function startBackgroundPreview(
// server, never a pre-existing unmanaged sibling.
const preLaunchPorts = sameProjectPorts(await scan(startPort), projectDir);
- const { pid, wrapperIdentity, logPath } = spawnDetachedPreview(
+ const { pid, wrapperIdentity, logPath, exitedWith } = spawnDetachedPreview(
projectDir,
stateHome,
dependencies,
);
const kill = dependencies.kill ?? stopProcess;
- const server = await awaitStartedServer(projectDir, startPort, preLaunchPorts, pid, dependencies);
+ const server = await awaitStartedServer(
+ projectDir,
+ startPort,
+ preLaunchPorts,
+ pid,
+ exitedWith,
+ dependencies,
+ );
if (!server) {
+ const exit = exitedWith();
+ if (exit) {
+ throw new Error(
+ `background preview exited (${exit}) before it was ready; see ${logPath}${logTail(logPath)}`,
+ );
+ }
await kill(pid);
throw new Error(`background preview did not become ready; see ${logPath}`);
}
@@ -587,16 +615,27 @@ export async function startBackgroundPreview(
};
}
+function logTail(logPath: string): string {
+ try {
+ const text = stripVTControlCharacters(readFileSync(logPath, "utf8"));
+ const lines = text.trimEnd().split("\n").slice(-5);
+ return lines.join("").trim() ? `\n${lines.join("\n")}` : "";
+ } catch {
+ return "";
+ }
+}
+
async function awaitStartedServer(
projectDir: string,
startPort: number,
preLaunchPorts: Set<number>,
launchedPid: number,
+ exitedWith: () => string | null,
dependencies: LifecycleDependencies,
): Promise<ActiveServer | null> {
const scan = dependencies.scan ?? scanActiveServers;
const sleep = dependencies.sleep ?? delay;
- for (let attempt = 0; attempt < 50; attempt++) {
+ for (let attempt = 0; attempt < 50 && !exitedWith(); attempt++) {
const server = startedServer(
await scan(startPort),
projectDir,