browser-debugger-cli 0.14.0 → 0.15.0

package/dist/connection/launcher/flagsBuilder.js

@@ -68,6 +68,103 @@ export function isDocker() {
         return false;
     }
 }
+const DISABLE_FEATURES = '--disable-features=';
+const ENABLE_FEATURES = '--enable-features=';
+/**
+ * Flags that bdg merges into one: Chrome reads only the last occurrence of
+ * these comma-separated feature lists, and chrome-launcher's defaults, bdg and
+ * users all pass them. `--disable-blink-features`/`--enable-blink-features`
+ * are not merged (neither bdg nor the defaults pass them), nor is `--js-flags`
+ * (space-separated V8 flags, not a feature list).
+ */
+const FEATURE_LIST_FLAGS = [DISABLE_FEATURES, ENABLE_FEATURES];
+/**
+ * Bare name of a feature-list entry, without a `<Trial` or `:params` suffix.
+ *
+ * @param entry - Entry such as `Foo<Trial` or `Foo:param/1`
+ * @returns Feature name
+ */
+function featureName(entry) {
+    return entry.split(/[<:]/)[0] ?? entry;
+}
+/**
+ * Remove disabled features that are also enabled.
+ *
+ * Chrome lets `--disable-features` win over `--enable-features`, so without
+ * this a user's `--enable-features=MediaRouter` could not re-enable a feature
+ * chrome-launcher disables by default.
+ *
+ * @param features - Merged values per feature-list flag (changed in place)
+ */
+function dropReEnabledFeatures(features) {
+    const enabled = new Set([...(features.get(ENABLE_FEATURES) ?? [])].map(featureName));
+    const disabled = features.get(DISABLE_FEATURES);
+    disabled?.forEach((entry) => {
+        if (enabled.has(featureName(entry)))
+            disabled.delete(entry);
+    });
+}
+/**
+ * Merge every `--disable-features=` (and `--enable-features=`) flag into one
+ * and drop repeated flags.
+ *
+ * Chrome applies only the last occurrence of a feature-list flag, so bdg's or
+ * the user's list would otherwise switch chrome-launcher's defaults back on.
+ * The merged flag keeps the first one's position; its values keep their order
+ * without repeats, and an enabled feature is never also disabled. Only
+ * entries starting with `-` are deduplicated, so positional arguments such as
+ * URLs are passed as given.
+ *
+ * @param flags - Chrome flags in launch order
+ * @returns Flags with at most one flag per feature list and no repeated flags
+ */
+function mergeFeatureFlags(flags) {
+    const features = new Map();
+    const merged = [];
+    for (const flag of flags) {
+        const prefix = FEATURE_LIST_FLAGS.find((p) => flag.startsWith(p));
+        if (prefix) {
+            if (!features.has(prefix))
+                merged.push(prefix);
+            const values = flag.slice(prefix.length).split(',').filter(Boolean);
+            features.set(prefix, new Set([...(features.get(prefix) ?? []), ...values]));
+        }
+        else if (!flag.startsWith('-') || !merged.includes(flag)) {
+            merged.push(flag);
+        }
+    }
+    dropReEnabledFeatures(features);
+    return merged.flatMap((flag) => {
+        const values = features.get(flag);
+        if (!values)
+            return [flag];
+        return values.size > 0 ? [flag + [...values].join(',')] : [];
+    });
+}
+/**
+ * Remove `HEADLESS` from this process's environment.
+ *
+ * chrome-launcher adds a bare `--headless` whenever the launching process has
+ * a non-empty `HEADLESS` variable (even `0` or `false`), whatever its
+ * `envVars` option says, which would make `--no-headless` launch headless.
+ * The daemon calls this before it launches Chrome.
+ *
+ * @param env - Environment to clean (defaults to `process.env`)
+ */
+export function dropLauncherHeadlessEnv(env = process.env) {
+    delete env['HEADLESS'];
+}
+/**
+ * chrome-launcher's default flags (plus its Linux sandbox flag). bdg passes
+ * them itself and tells chrome-launcher to skip its own copy, so each flag
+ * appears once; chrome-launcher adds `--remote-debugging-port`.
+ *
+ * @returns Default flags
+ */
+function defaultFlags() {
+    const flags = chromeLauncher.Launcher.defaultFlags();
+    return process.platform === 'linux' ? [...flags, '--disable-setuid-sandbox'] : flags;
+}
 /**
  * Build Chrome flags array from launch options.
  *
@@ -80,6 +177,8 @@ export function isDocker() {
  *
  * Custom flags are passed via the chromeFlags option. The BDG_CHROME_FLAGS env var
  * is parsed by the CLI and merged into chromeFlags before reaching this function.
+ * Feature lists from all sources end up in one `--disable-features` (and one
+ * `--enable-features`) flag, and each flag appears once.
  *
  * @param options - Launch options containing flag preferences
  * @returns Array of Chrome command-line flags
@@ -101,17 +200,6 @@ export function isDocker() {
  * // Includes --disable-gpu, --no-sandbox if in Docker
  * ```
  */
-/**
- * chrome-launcher's default flags (plus its Linux sandbox flag). bdg passes
- * them itself and tells chrome-launcher to skip its own copy, so each flag
- * appears once; chrome-launcher adds `--remote-debugging-port`.
- *
- * @returns Default flags
- */
-function defaultFlags() {
-    const flags = chromeLauncher.Launcher.defaultFlags();
-    return process.platform === 'linux' ? [...flags, '--disable-setuid-sandbox'] : flags;
-}
 export function buildChromeFlags(options) {
     const baseFlags = options.ignoreDefaultFlags ? [] : defaultFlags();
     const bdgFlags = [
@@ -120,18 +208,14 @@ export function buildChromeFlags(options) {
     ];
     const dockerFlags = isDocker() ? DOCKER_CHROME_FLAGS : [];
     const sandboxFlags = needsNoSandbox() ? ['--no-sandbox'] : [];
-    // Custom flags from CLI option (env var BDG_CHROME_FLAGS is parsed by CLI and passed here)
     const customFlags = options.chromeFlags ?? [];
-    if (options.headless) {
-        return [
-            HEADLESS_FLAG,
-            ...baseFlags,
-            ...bdgFlags,
-            ...dockerFlags,
-            ...sandboxFlags,
-            ...customFlags,
-        ];
-    }
-    return [...baseFlags, ...bdgFlags, ...dockerFlags, ...sandboxFlags, ...customFlags];
+    return mergeFeatureFlags([
+        ...(options.headless ? [HEADLESS_FLAG] : []),
+        ...baseFlags,
+        ...bdgFlags,
+        ...dockerFlags,
+        ...sandboxFlags,
+        ...customFlags,
+    ]);
 }
 //# sourceMappingURL=flagsBuilder.js.map

package/dist/connection/launcher.d.ts

@@ -4,7 +4,7 @@ import type { Options as ChromeLaunchOptions } from 'chrome-launcher';
  * Options that control how Chrome is launched for CDP sessions.
  * Extended to support chrome-launcher advanced features.
  */
-export interface LaunchOptions extends Pick<ChromeLaunchOptions, 'logLevel' | 'connectionPollInterval' | 'maxConnectionRetries' | 'portStrictMode' | 'envVars' | 'handleSIGINT' | 'ignoreDefaultFlags' | 'chromeFlags' | 'chromePath'> {
+export interface LaunchOptions extends Pick<ChromeLaunchOptions, 'logLevel' | 'connectionPollInterval' | 'maxConnectionRetries' | 'portStrictMode' | 'envVars' | 'ignoreDefaultFlags' | 'chromeFlags' | 'chromePath'> {
     /** Remote debugging port (defaults to 9222 when omitted) */
     port?: number;
     /**

package/dist/connection/launcher.js

@@ -2,7 +2,7 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import * as chromeLauncher from 'chrome-launcher';
-import { BDG_CHROME_PREFS, DEFAULT_CDP_PORT, CHROME_PROFILE_DIR, DEFAULT_CHROME_LOG_LEVEL, DEFAULT_CHROME_HANDLE_SIGINT, } from '../constants.js';
+import { BDG_CHROME_PREFS, DEFAULT_CDP_PORT, CHROME_PROFILE_DIR, DEFAULT_CHROME_LOG_LEVEL, } from '../constants.js';
 import { makeDirectory } from '../utils/directories.js';
 import { getErrorMessage } from '../utils/errors.js';
 import { filterDefined } from '../utils/objects.js';
@@ -224,7 +224,6 @@ function buildChromeOptions(options) {
     const chromePathOverride = resolveChromeBinary(options);
     return {
         logLevel: options.logLevel ?? DEFAULT_CHROME_LOG_LEVEL,
-        handleSIGINT: options.handleSIGINT ?? DEFAULT_CHROME_HANDLE_SIGINT,
         ignoreDefaultFlags: true,
         chromeFlags: buildChromeFlags(options),
         userDataDir,

package/dist/constants.d.ts

@@ -12,10 +12,6 @@ export declare const DEFAULT_CDP_PORT = 9222;
  * Default Chrome launcher log level for quiet operation
  */
 export declare const DEFAULT_CHROME_LOG_LEVEL = "silent";
-/**
- * Default SIGINT handling - bdg handles signals, not chrome-launcher
- */
-export declare const DEFAULT_CHROME_HANDLE_SIGINT = false;
 /**
  * Persistent Chrome profile directory path (relative to user home)
  */
@@ -124,6 +120,8 @@ export declare const CHROME_NETWORK_BUFFER_PER_RESOURCE: number;
 export declare const CHROME_POST_DATA_LIMIT: number;
 /** Matches `dom query` and `dom a11y query` list with `--json` and no `--limit` */
 export declare const QUERY_JSON_LIST_LIMIT = 100;
+/** Elements of an array result `dom eval --json` lists (the rest are counted as omitted) */
+export declare const EVAL_JSON_ARRAY_LIMIT = 100;
 /** Matches `dom layout` measures per command (the rest are counted as omitted) */
 export declare const LAYOUT_ELEMENT_LIMIT = 100;
 /**

package/dist/constants.js

@@ -15,10 +15,6 @@ export const DEFAULT_CDP_PORT = 9222;
  * Default Chrome launcher log level for quiet operation
  */
 export const DEFAULT_CHROME_LOG_LEVEL = 'silent';
-/**
- * Default SIGINT handling - bdg handles signals, not chrome-launcher
- */
-export const DEFAULT_CHROME_HANDLE_SIGINT = false;
 /**
  * Persistent Chrome profile directory path (relative to user home)
  */
@@ -165,6 +161,8 @@ export const CHROME_POST_DATA_LIMIT = 1 * 1024 * 1024; // 1MB
 // ============================================================================
 /** Matches `dom query` and `dom a11y query` list with `--json` and no `--limit` */
 export const QUERY_JSON_LIST_LIMIT = 100;
+/** Elements of an array result `dom eval --json` lists (the rest are counted as omitted) */
+export const EVAL_JSON_ARRAY_LIMIT = 100;
 /** Matches `dom layout` measures per command (the rest are counted as omitted) */
 export const LAYOUT_ELEMENT_LIMIT = 100;
 /**

package/dist/daemon/launcher.d.ts

@@ -16,6 +16,8 @@ export interface SpawnedDaemon {
  * Ensure a daemon is running, spawning one if needed.
  *
  * @returns The daemon it spawned, or undefined when one was already running
+ * @throws SessionDirError if the session directory is unusable or untrusted
+ *   (checked first, so a socket planted there is never taken for a daemon)
  * @throws DaemonStartupError if the daemon script is missing or the daemon
  *   does not accept connections in time
  */
@@ -24,9 +26,21 @@ export declare function launchDaemon(): Promise<SpawnedDaemon | undefined>;
  * Check that the session directory can hold the daemon's files before
  * spawning it (otherwise the daemon dies and only its log says why).
  *
- * @throws SessionDirError (103) for a file or a path that cannot hold a
- *   directory (a pseudo-filesystem like `/proc`), (81) for a too-long path
- *   like a named session's, (82) when not writable
+ * @throws SessionDirError (103) for a file, a path that cannot hold a
+ *   directory (a pseudo-filesystem like `/proc`) or an untrusted directory
+ *   (see {@link secureSessionDir}, which also tightens the user's own 0755
+ *   directories to 0700), (81) for a too-long path like a named session's,
+ *   (82) when not writable
  */
 export declare function assertUsableSessionDir(): void;
+/**
+ * Open the daemon log for the daemon's output, creating it 0600. A symlink in
+ * its place is refused, not followed: it would append the log to the file it
+ * points to.
+ *
+ * @param logPath - Daemon log path
+ * @returns File descriptor
+ * @throws SessionDirError (103) when it cannot be opened (`ELOOP` for a symlink)
+ */
+export declare function openDaemonLog(logPath: string): number;
 //# sourceMappingURL=launcher.d.ts.map

package/dist/daemon/launcher.js

@@ -10,10 +10,10 @@ import { spawn } from 'child_process';
 import fs from 'fs';
 import { join } from 'path';
 import { DaemonStartupError, SessionDirError } from './errors.js';
-import { sessionDirIsFileError, sessionDirNotWritableError, socketPathTooLongError, } from '../errors/messages.js';
+import { daemonLogNotOpenedError, sessionDirIsFileError, sessionDirNotWritableError, socketPathTooLongError, untrustedSessionDirError, } from '../errors/messages.js';
 import { killSessionChromes, readLiveDaemonPid } from '../session/cleanup/staleSession.js';
 import { isDaemonAlive, isDaemonSocketGone } from '../session/daemonSocket.js';
-import { MAX_DAEMON_SOCKET_PATH_BYTES, ensureSessionDir, getSessionDir, getSessionFilePath, } from '../session/paths.js';
+import { MAX_DAEMON_SOCKET_PATH_BYTES, ensureSessionDir, getSessionDir, getSessionFilePath, secureSessionDir, } from '../session/paths.js';
 import { createLogger } from '../ui/logging/index.js';
 import { delay } from '../utils/async.js';
 import { directoryProblem } from '../utils/directories.js';
@@ -28,10 +28,13 @@ const DAEMON_READY_POLL_MS = 20;
  * Ensure a daemon is running, spawning one if needed.
  *
  * @returns The daemon it spawned, or undefined when one was already running
+ * @throws SessionDirError if the session directory is unusable or untrusted
+ *   (checked first, so a socket planted there is never taken for a daemon)
  * @throws DaemonStartupError if the daemon script is missing or the daemon
  *   does not accept connections in time
  */
 export async function launchDaemon() {
+    assertUsableSessionDir();
     if (await isDaemonAlive()) {
         log.debug('Daemon already running');
         return undefined;
@@ -39,11 +42,10 @@ export async function launchDaemon() {
     if (!fs.existsSync(DAEMON_SCRIPT_PATH)) {
         throw new DaemonStartupError(`Daemon script not found at ${DAEMON_SCRIPT_PATH}. Did you run 'npm run build'?`, 'DAEMON_SCRIPT_NOT_FOUND');
     }
-    assertUsableSessionDir();
     await stopUnreachableDaemon();
     const logPath = join(getSessionDir(), 'daemon.log');
     rotateLog(logPath);
-    const logFd = fs.openSync(logPath, 'a');
+    const logFd = openDaemonLog(logPath);
     log.debug(`Starting daemon: ${DAEMON_SCRIPT_PATH}`);
     const daemon = spawn(process.execPath, [DAEMON_SCRIPT_PATH], {
         detached: true,
@@ -97,9 +99,11 @@ async function stopUnreachableDaemon() {
  * Check that the session directory can hold the daemon's files before
  * spawning it (otherwise the daemon dies and only its log says why).
  *
- * @throws SessionDirError (103) for a file or a path that cannot hold a
- *   directory (a pseudo-filesystem like `/proc`), (81) for a too-long path
- *   like a named session's, (82) when not writable
+ * @throws SessionDirError (103) for a file, a path that cannot hold a
+ *   directory (a pseudo-filesystem like `/proc`) or an untrusted directory
+ *   (see {@link secureSessionDir}, which also tightens the user's own 0755
+ *   directories to 0700), (81) for a too-long path like a named session's,
+ *   (82) when not writable
  */
 export function assertUsableSessionDir() {
     const dir = getSessionDir();
@@ -116,6 +120,9 @@ export function assertUsableSessionDir() {
     if (problem) {
         fail(sessionDirNotWritableError(dir, problem.reason), problem.denied ? EXIT_CODES.PERMISSION_DENIED : EXIT_CODES.SESSION_FILE_ERROR);
     }
+    const untrusted = secureSessionDir(dir);
+    if (untrusted)
+        fail(untrustedSessionDirError(untrusted));
     try {
         ensureSessionDir();
         fs.accessSync(dir, fs.constants.W_OK);
@@ -126,6 +133,29 @@ export function assertUsableSessionDir() {
         fail(sessionDirNotWritableError(dir, code ?? getErrorMessage(error)), denied ? EXIT_CODES.PERMISSION_DENIED : EXIT_CODES.SESSION_FILE_ERROR);
     }
 }
+/** Flags opening the daemon log for appending, refusing (not following) a symlink */
+const DAEMON_LOG_FLAGS = fs.constants.O_WRONLY |
+    fs.constants.O_APPEND |
+    fs.constants.O_CREAT |
+    (fs.constants.O_NOFOLLOW ?? 0);
+/**
+ * Open the daemon log for the daemon's output, creating it 0600. A symlink in
+ * its place is refused, not followed: it would append the log to the file it
+ * points to.
+ *
+ * @param logPath - Daemon log path
+ * @returns File descriptor
+ * @throws SessionDirError (103) when it cannot be opened (`ELOOP` for a symlink)
+ */
+export function openDaemonLog(logPath) {
+    try {
+        return fs.openSync(logPath, DAEMON_LOG_FLAGS, 0o600);
+    }
+    catch (error) {
+        const err = daemonLogNotOpenedError(logPath, error.code ?? getErrorMessage(error));
+        throw new SessionDirError(err.message, err.suggestion);
+    }
+}
 /** Size above which the daemon log is rotated when a daemon starts */
 const MAX_LOG_BYTES = 5 * 1024 * 1024;
 /**

package/dist/daemon/session/commandRegistry.js

@@ -452,8 +452,8 @@ export function createCommandRegistry(store, emulation) {
             return { result, ...(hint !== undefined && { hint }) };
         },
         dom_eval: async (cdp, params) => params.frame === undefined
-            ? evaluateScript(cdp, params.script)
-            : evaluateInFrame(cdp, pageWebSocketUrl(store), params.script, params.frame, listedFrameIds),
+            ? evaluateScript(cdp, params.script, { full: params.full ?? false })
+            : evaluateInFrame(cdp, pageWebSocketUrl(store), params.script, params.frame, listedFrameIds, params.full ?? false),
         dom_frames: async (cdp) => {
             const { frames, frameIds } = await listFrames(cdp, pageWebSocketUrl(store));
             listedFrameIds = frameIds;