browser-debugger-cli 0.7.2 → 0.9.0

package/dist/connection/launcher/flagsBuilder.js

@@ -9,20 +9,53 @@
  */
 import * as fs from 'fs';
 import * as chromeLauncher from 'chrome-launcher';
-import { BDG_CHROME_FLAGS, DEFAULT_CDP_PORT, HEADLESS_FLAG, DOCKER_CHROME_FLAGS, } from '../../constants.js';
-const REMOTE_DEBUGGING_FLAG = (port) => `--remote-debugging-port=${port}`;
+import { BDG_CHROME_FLAGS, HEADLESS_FLAG, DOCKER_CHROME_FLAGS } from '../../constants.js';
+/**
+ * Marker flag identifying a Chrome launched by bdg for a given session directory.
+ *
+ * Chrome ignores unknown switches; crash cleanup matches this exact string in a
+ * process's command line before killing it, so a reused PID (or the user's own
+ * debugging Chrome) is never mistaken for a bdg Chrome.
+ *
+ * @param sessionDir - bdg session directory
+ * @returns Marker flag
+ */
+export function chromeSessionMarkerFlag(sessionDir) {
+    return `--bdg-session-dir=${sessionDir}`;
+}
+/** Environment variable that forces `--no-sandbox` (e.g. in restricted containers). */
+const NO_SANDBOX_ENV = 'BDG_NO_SANDBOX';
+/**
+ * Whether Chrome must run with `--no-sandbox`.
+ *
+ * Only where the sandbox cannot work, so it stays on everywhere else
+ * (including Podman-based dev containers such as toolbox/distrobox):
+ * - Docker: the default seccomp profile blocks the user namespaces the
+ *   sandbox needs, for root and non-root users alike
+ * - root on Linux: Chrome refuses to start sandboxed as root
+ * - `BDG_NO_SANDBOX=1`: explicit opt-in for other restricted environments
+ *
+ * @returns True if `--no-sandbox` should be added
+ */
+export function needsNoSandbox() {
+    if (process.env[NO_SANDBOX_ENV] === '1')
+        return true;
+    if (process.platform === 'linux' && process.getuid?.() === 0)
+        return true;
+    return fs.existsSync('/.dockerenv');
+}
 /**
  * Check if running inside a Docker container.
  *
- * Detects Docker environment by checking for:
- * 1. /.dockerenv file (standard Docker indicator)
- * 2. "docker" or "containerd" in /proc/self/cgroup
+ * Detects a container by checking for:
+ * 1. /.dockerenv (Docker) or /run/.containerenv (Podman)
+ * 2. "docker" or "containerd" in /proc/self/cgroup (cgroup v1 hosts)
  *
  * @returns True if running in Docker, false otherwise
  */
 export function isDocker() {
     try {
-        if (fs.existsSync('/.dockerenv')) {
+        if (fs.existsSync('/.dockerenv') || fs.existsSync('/run/.containerenv')) {
             return true;
         }
         if (fs.existsSync('/proc/self/cgroup')) {
@@ -35,35 +68,6 @@ export function isDocker() {
         return false;
     }
 }
-/**
- * Parse custom Chrome flags from BDG_CHROME_FLAGS environment variable.
- *
- * NOTE: This function is deprecated for use in the daemon/worker. The env var
- * is now parsed by the CLI (src/commands/start.ts) and passed via IPC to ensure
- * the env var set when running `bdg` reaches the worker process.
- *
- * Supports space-separated flags, with proper handling of flags containing
- * equals signs (e.g., --window-size=1920,1080).
- *
- * @returns Array of Chrome flags parsed from environment variable
- * @deprecated Use CLI parsing instead - kept for test compatibility
- *
- * @example
- * ```bash
- * # Single flag
- * BDG_CHROME_FLAGS="--ignore-certificate-errors" bdg https://localhost:5173
- *
- * # Multiple flags
- * BDG_CHROME_FLAGS="--ignore-certificate-errors --disable-web-security" bdg https://localhost:5173
- * ```
- */
-export function getEnvChromeFlags() {
-    const envFlags = process.env['BDG_CHROME_FLAGS'];
-    if (!envFlags) {
-        return [];
-    }
-    return envFlags.split(' ').filter(Boolean);
-}
 /**
  * Build Chrome flags array from launch options.
  *
@@ -97,16 +101,37 @@ export function getEnvChromeFlags() {
  * // 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 port = options.port ?? DEFAULT_CDP_PORT;
-    const baseFlags = options.ignoreDefaultFlags ? [] : chromeLauncher.Launcher.defaultFlags();
-    const bdgFlags = [REMOTE_DEBUGGING_FLAG(port), ...BDG_CHROME_FLAGS];
+    const baseFlags = options.ignoreDefaultFlags ? [] : defaultFlags();
+    const bdgFlags = [
+        ...(options.sessionDir ? [chromeSessionMarkerFlag(options.sessionDir)] : []),
+        ...BDG_CHROME_FLAGS,
+    ];
     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, ...customFlags];
+        return [
+            HEADLESS_FLAG,
+            ...baseFlags,
+            ...bdgFlags,
+            ...dockerFlags,
+            ...sandboxFlags,
+            ...customFlags,
+        ];
     }
-    return [...baseFlags, ...bdgFlags, ...dockerFlags, ...customFlags];
+    return [...baseFlags, ...bdgFlags, ...dockerFlags, ...sandboxFlags, ...customFlags];
 }
 //# sourceMappingURL=flagsBuilder.js.map

package/dist/connection/launcher/preferencesLoader.js

@@ -5,8 +5,7 @@
  * and validates that they are JSON-serializable for chrome-launcher compatibility.
  */
 import * as fs from 'fs';
-import { ChromeLaunchError } from '../../connection/errors.js';
-import { prefsFileNotFoundError, invalidPrefsFormatError, prefsLoadError, } from '../../ui/messages/chrome.js';
+import { ChromeLaunchError } from '../errors.js';
 import { getErrorMessage } from '../../utils/errors.js';
 /**
  * Load Chrome preferences from file or inline options.
@@ -37,14 +36,22 @@ import { getErrorMessage } from '../../utils/errors.js';
  */
 export function loadChromePrefs(options) {
     if (options.prefsFile) {
-        if (!fs.existsSync(options.prefsFile)) {
-            throw new ChromeLaunchError(prefsFileNotFoundError(options.prefsFile), new Error('File does not exist'));
+        const file = options.prefsFile;
+        if (!fs.existsSync(file)) {
+            throw new ChromeLaunchError(`Chrome preferences file not found: ${file}`, {
+                issue: { code: 'PREFS_FILE_NOT_FOUND', context: { file } },
+            });
         }
         try {
-            const prefsContent = fs.readFileSync(options.prefsFile, 'utf8');
+            const prefsContent = fs.readFileSync(file, 'utf8');
             const parsed = JSON.parse(prefsContent);
             if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
-                throw new ChromeLaunchError(invalidPrefsFormatError(options.prefsFile, typeof parsed), new Error('Invalid JSON structure'));
+                throw new ChromeLaunchError(`Invalid Chrome preferences format in ${file}: expected object, got ${typeof parsed}`, {
+                    issue: {
+                        code: 'PREFS_INVALID_FORMAT',
+                        context: { file, actualType: Array.isArray(parsed) ? 'array' : typeof parsed },
+                    },
+                });
             }
             return parsed;
         }
@@ -52,7 +59,13 @@ export function loadChromePrefs(options) {
             if (error instanceof ChromeLaunchError) {
                 throw error;
             }
-            throw new ChromeLaunchError(prefsLoadError(options.prefsFile, getErrorMessage(error)), error instanceof Error ? error : undefined);
+            throw new ChromeLaunchError(`Failed to load Chrome preferences from ${file}`, {
+                ...(error instanceof Error && { cause: error }),
+                issue: {
+                    code: 'PREFS_LOAD_FAILED',
+                    context: { file, reason: getErrorMessage(error) },
+                },
+            });
         }
     }
     return options.prefs;
@@ -83,7 +96,13 @@ export function ensureJSONCompatiblePrefs(prefs) {
         JSON.stringify(prefs);
     }
     catch (error) {
-        throw new ChromeLaunchError(`Chrome preferences must be JSON-serializable: ${getErrorMessage(error)}`, error instanceof Error ? error : undefined);
+        throw new ChromeLaunchError('Chrome preferences must be JSON-serializable', {
+            ...(error instanceof Error && { cause: error }),
+            issue: {
+                code: 'PREFS_NOT_JSON_SERIALIZABLE',
+                context: { reason: getErrorMessage(error) },
+            },
+        });
     }
     return prefs;
 }

package/dist/connection/launcher/profilePreferences.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Chrome profile preferences writer.
+ *
+ * Chrome reads `<user-data-dir>/Default/Preferences` as nested JSON and looks
+ * preferences up by path (`profile.password_manager_enabled` is
+ * `{"profile": {"password_manager_enabled": ...}}`). bdg's preferences use
+ * dotted names, so they are expanded into that structure and deep-merged into
+ * the existing file: persistent profiles reused across sessions get them too,
+ * and everything else Chrome stored there is kept.
+ */
+import type { Logger } from '../types.js';
+/** JSON object as stored in the Preferences file */
+type PrefsObject = Record<string, unknown>;
+/**
+ * Merge preferences into an existing Preferences object.
+ *
+ * Dotted names become nested paths, and a literal dotted top-level key (as
+ * earlier bdg versions wrote, which Chrome ignored) is removed.
+ *
+ * @param existing - Current Preferences content
+ * @param prefs - Preferences to apply, dotted or nested
+ * @returns Merged Preferences (a new object; `existing` is not modified)
+ */
+export declare function mergePreferences(existing: PrefsObject, prefs: PrefsObject): PrefsObject;
+/**
+ * Whether a running Chrome has the profile open, judged by its
+ * `SingletonLock` symlink (`<host>-<pid>`, macOS and Linux).
+ *
+ * @param userDataDir - Chrome user data directory
+ * @returns True if the lock names a live process on this host
+ */
+export declare function profileInUse(userDataDir: string): boolean;
+/**
+ * Apply preferences to the default profile in a Chrome user data directory.
+ *
+ * Failures are logged (visible in daemon.log), not thrown: Chrome still
+ * starts, only without them. An unreadable Preferences file and a profile
+ * that a running Chrome has open are left alone, and the file is not
+ * rewritten when nothing changes.
+ *
+ * @param userDataDir - Chrome user data directory
+ * @param prefs - Preferences to apply, dotted or nested
+ * @param logger - Logger for failures
+ */
+export declare function writeProfilePreferences(userDataDir: string, prefs: PrefsObject, logger: Logger): void;
+export {};
+//# sourceMappingURL=profilePreferences.d.ts.map

package/dist/connection/launcher/profilePreferences.js

@@ -0,0 +1,151 @@
+/**
+ * Chrome profile preferences writer.
+ *
+ * Chrome reads `<user-data-dir>/Default/Preferences` as nested JSON and looks
+ * preferences up by path (`profile.password_manager_enabled` is
+ * `{"profile": {"password_manager_enabled": ...}}`). bdg's preferences use
+ * dotted names, so they are expanded into that structure and deep-merged into
+ * the existing file: persistent profiles reused across sessions get them too,
+ * and everything else Chrome stored there is kept.
+ */
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { chromePrefsNotAppliedMessage } from '../../ui/messages/chrome.js';
+import { getErrorMessage } from '../../utils/errors.js';
+import { isProcessAlive } from '../../utils/process.js';
+/**
+ * Whether a value is a plain JSON object (not an array or null).
+ *
+ * @param value - Value to check
+ * @returns True for objects that can be merged into
+ */
+function isPrefsObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Set a preference at a nested path, merging objects with what is there.
+ *
+ * @param target - Preferences object to modify
+ * @param keys - Path segments, e.g. `['profile', 'exit_type']`
+ * @param value - Value to set
+ */
+function setAtPath(target, keys, value) {
+    const [key, ...rest] = keys;
+    if (key === undefined)
+        return;
+    const current = target[key];
+    if (rest.length > 0) {
+        const child = isPrefsObject(current) ? current : {};
+        target[key] = child;
+        setAtPath(child, rest, value);
+        return;
+    }
+    if (isPrefsObject(current) && isPrefsObject(value)) {
+        for (const [childKey, childValue] of Object.entries(value)) {
+            setAtPath(current, [childKey], childValue);
+        }
+        return;
+    }
+    target[key] = value;
+}
+/**
+ * Merge preferences into an existing Preferences object.
+ *
+ * Dotted names become nested paths, and a literal dotted top-level key (as
+ * earlier bdg versions wrote, which Chrome ignored) is removed.
+ *
+ * @param existing - Current Preferences content
+ * @param prefs - Preferences to apply, dotted or nested
+ * @returns Merged Preferences (a new object; `existing` is not modified)
+ */
+export function mergePreferences(existing, prefs) {
+    const merged = structuredClone(existing);
+    for (const [name, value] of Object.entries(prefs)) {
+        if (name.includes('.'))
+            delete merged[name];
+        setAtPath(merged, name.split('.'), value);
+    }
+    return merged;
+}
+/**
+ * Read the profile's Preferences file.
+ *
+ * @param file - Preferences file path
+ * @returns Its content, `{}` if missing
+ * @throws Error if it is not valid JSON or not a JSON object
+ */
+function readPreferencesFile(file) {
+    if (!fs.existsSync(file))
+        return {};
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (!isPrefsObject(parsed))
+        throw new Error('not a JSON object');
+    return parsed;
+}
+/**
+ * Whether a running Chrome has the profile open, judged by its
+ * `SingletonLock` symlink (`<host>-<pid>`, macOS and Linux).
+ *
+ * @param userDataDir - Chrome user data directory
+ * @returns True if the lock names a live process on this host
+ */
+export function profileInUse(userDataDir) {
+    let target;
+    try {
+        target = fs.readlinkSync(path.join(userDataDir, 'SingletonLock'));
+    }
+    catch {
+        return false;
+    }
+    const separator = target.lastIndexOf('-');
+    const pid = Number(target.slice(separator + 1));
+    return (target.slice(0, separator) === os.hostname() && Number.isInteger(pid) && isProcessAlive(pid));
+}
+/**
+ * Replace a file atomically: write a temporary file next to it, then rename.
+ *
+ * @param file - File to replace
+ * @param content - New content
+ */
+function writeFileAtomic(file, content) {
+    const temp = `${file}.bdg-${process.pid}.tmp`;
+    try {
+        fs.writeFileSync(temp, content, 'utf8');
+        fs.renameSync(temp, file);
+    }
+    finally {
+        fs.rmSync(temp, { force: true });
+    }
+}
+/**
+ * Apply preferences to the default profile in a Chrome user data directory.
+ *
+ * Failures are logged (visible in daemon.log), not thrown: Chrome still
+ * starts, only without them. An unreadable Preferences file and a profile
+ * that a running Chrome has open are left alone, and the file is not
+ * rewritten when nothing changes.
+ *
+ * @param userDataDir - Chrome user data directory
+ * @param prefs - Preferences to apply, dotted or nested
+ * @param logger - Logger for failures
+ */
+export function writeProfilePreferences(userDataDir, prefs, logger) {
+    const file = path.join(userDataDir, 'Default', 'Preferences');
+    if (profileInUse(userDataDir)) {
+        logger.info(chromePrefsNotAppliedMessage(file, 'the profile is in use by a running Chrome'));
+        return;
+    }
+    try {
+        const existing = readPreferencesFile(file);
+        const content = JSON.stringify(mergePreferences(existing, prefs));
+        if (content === JSON.stringify(existing))
+            return;
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        writeFileAtomic(file, content);
+    }
+    catch (error) {
+        logger.info(chromePrefsNotAppliedMessage(file, getErrorMessage(error)));
+    }
+}
+//# sourceMappingURL=profilePreferences.js.map

package/dist/connection/launcher.d.ts

@@ -7,7 +7,11 @@ import type { Options as ChromeLaunchOptions } from 'chrome-launcher';
 export interface LaunchOptions extends Pick<ChromeLaunchOptions, 'logLevel' | 'connectionPollInterval' | 'maxConnectionRetries' | 'portStrictMode' | 'envVars' | 'handleSIGINT' | 'ignoreDefaultFlags' | 'chromeFlags' | 'chromePath'> {
     /** Remote debugging port (defaults to 9222 when omitted) */
     port?: number;
-    /** Directory for Chrome profile data. Falls back to persistent ~/.bdg/chrome-profile directory */
+    /**
+     * Directory for Chrome profile data, chosen by the user: bdg's default
+     * preferences are not written into it. Falls back to the bdg-managed
+     * persistent profile in the session directory (~/.bdg/chrome-profile)
+     */
     userDataDir?: string | undefined;
     /** Base directory for creating user data dir (defaults to OS temp dir, injectable for testing) */
     baseDir?: string | undefined;
@@ -23,6 +27,8 @@ export interface LaunchOptions extends Pick<ChromeLaunchOptions, 'logLevel' | 'c
     prefsFile?: string | undefined;
     /** Override Chrome binary detection with an explicit path */
     chromePath?: string;
+    /** bdg session directory: recorded as a marker flag on the Chrome command line, and holds the default profile */
+    sessionDir?: string | undefined;
 }
 /**
  * Launch Chrome with remote debugging enabled using chrome-launcher.
@@ -44,4 +50,19 @@ export interface LaunchOptions extends Pick<ChromeLaunchOptions, 'logLevel' | 'c
  * Uses chrome-launcher for cross-platform Chrome detection and launching.
  */
 export declare function launchChrome(options?: LaunchOptions): Promise<LaunchedChrome>;
+/**
+ * Preferences for the launched profile: bdg's defaults (no translate prompt,
+ * no password manager or leak check, whose bubbles capture input) for
+ * profiles bdg manages, with the caller's preferences on top. A profile the
+ * user chose (`--user-data-dir`) gets only preferences the caller passed.
+ *
+ * File-based preferences take precedence over inline preferences because
+ * files allow for complex, reusable configurations that can be version
+ * controlled and shared across team members or CI environments.
+ *
+ * @param options - Launch options containing prefs or prefsFile
+ * @returns Merged preferences (empty when there is nothing to apply)
+ * @throws ChromeLaunchError if prefs file cannot be read or parsed, or prefs are not JSON
+ */
+export declare function resolveChromePrefs(options: LaunchOptions): Record<string, unknown>;
 //# sourceMappingURL=launcher.d.ts.map