Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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,