Files
hyperframes/packages/cli/src/utils/openBrowser.ts
T
Miguel Ángel 6cf4b56697 fix(engine): a render on Windows opens no console windows (#6613)
* ci(windows): probe that a render opens no visible window

* ci(windows): the probe names what opened each window

* ci(windows): the probe spawns each binary alone, with and without detached

* ci(windows): the probe logs the processes started during the render

* ci(windows): the probe also spawns Chrome one consoleless hop down

* ci(windows): the probe logs each child started without windowsHide

* ci(windows): the probe logs every child process with its windowsHide and detached

* fix(engine): Chrome keeps the CLI's console on Windows, so a render opens no window

* fix(cli): every child the CLI starts on Windows is hidden unless it opts out

* ci(windows): the probe bisects Chrome's flags and keeps each command's output

* ci(windows): the probe names the Chrome process behind each window

* ci(windows): the probe loads a page in Chrome directly and one hidden hop down

* ci(windows): the probe prints the Chrome main command line and renders with the reporter's flags

* ci(windows): the probe narrows the CLI's Chrome arguments to the ones that open a window

* ci(windows): the probe launches the CLI's Chrome arguments one hidden hop down

* ci(windows): the probe launches Chrome through the engine's browser pool

* ci(windows): the probe varies what the engine passes to Puppeteer

* fix(engine): renders on Windows launch Chrome with a Puppeteer that keeps it attached

* refactor(cli): hideChildConsoles copies its arguments and keeps one comment line
2026-10-28 07:48:40 +00:00

87 lines
3.0 KiB
TypeScript

import { spawn } from "node:child_process";
import { parsePort } from "./port.js";
export interface OpenBrowserOptions {
browserPath?: string;
userDataDir?: string;
remoteDebuggingPort?: number;
/**
* Launch the browser with --disable-gpu. For hosts where hardware
* acceleration crashes the graphics driver (wild report: auto-opened
* preview triggered NVIDIA Xid 32 resets on NixOS). Only effective with
* `browserPath` — the `open`-package fallback launches the system default
* browser with no way to pass Chromium flags.
*/
disableGpu?: boolean;
}
export function parseRemoteDebuggingPort(value: string | undefined): number | undefined {
if (value === undefined || value === "") return undefined;
return parsePort(value, "--remote-debugging-port");
}
export interface RemoteDebuggingPortDeps {
browserPath?: string;
userDataDir?: string;
remoteDebuggingPort?: string;
}
/**
* Returns an error message if --remote-debugging-port is set without its required
* dependencies (--browser-path and --user-data-dir), or null if everything is OK.
*/
export function validateRemoteDebuggingPortDeps(deps: RemoteDebuggingPortDeps): string | null {
if (!deps.remoteDebuggingPort) return null;
if (!deps.browserPath) return "--remote-debugging-port requires --browser-path";
if (!deps.userDataDir) return "--remote-debugging-port requires --user-data-dir";
return null;
}
/**
* Build the argument list for spawning a browser process.
*
* Pure function — easy to unit-test without mocking `spawn` or `import("open")`.
*/
export function buildBrowserArgs(url: string, options: OpenBrowserOptions): string[] {
const args: string[] = [];
if (options.userDataDir) {
args.push(`--user-data-dir=${options.userDataDir}`);
}
// Defense-in-depth: only emit --remote-debugging-port when paired with an
// isolated --user-data-dir. Without an isolated profile the CDP endpoint
// would expose the user's main browser session, which is the whole reason
// the CLI validation layer requires both flags together.
if (options.remoteDebuggingPort !== undefined && options.userDataDir) {
args.push(`--remote-debugging-port=${options.remoteDebuggingPort}`);
}
if (options.disableGpu) {
args.push("--disable-gpu");
}
args.push(url);
return args;
}
/**
* Open a URL in the browser with the given options.
*
* - browserPath: spawn the given binary directly (enables Chromium flags)
* - userDataDir: passed as --user-data-dir (requires browserPath)
* - remoteDebuggingPort: passed as --remote-debugging-port (requires browserPath + userDataDir)
* - otherwise: fall back to the `open` package (default browser)
*/
export function openBrowser(url: string, options: OpenBrowserOptions = {}): void {
if (options.browserPath) {
const args = buildBrowserArgs(url, options);
const child = spawn(options.browserPath, args, {
detached: true,
stdio: "ignore",
windowsHide: false,
});
child.on("error", () => {});
child.unref();
return;
}
import("open").then((mod) => mod.default(url)).catch(() => {});
}