browser-debugger-cli 0.14.0 → 0.15.0

package/.claude/skills/bdg/SKILL.md

@@ -126,7 +126,7 @@ bdg details network <id>                      # Headers, timing, body of one req
 bdg network getCookies
 bdg console --level error                     # Errors on the current page
 bdg console --follow                          # Streams (blocks; agents re-run bdg console instead)
-bdg network har /tmp/session.har              # Export HAR 1.2
+bdg network har /tmp/session.har              # Export HAR 1.2 (credentials redacted; --include-sensitive keeps them)
 ```
 
 ## Raw CDP

package/dist/commands/cdp.js

@@ -80,6 +80,7 @@ function getMethodHint(methodName, result) {
 export function registerCdpCommand(program) {
     program
         .command('cdp')
+        .summary('CDP protocol introspection and execution')
         .description('CDP protocol introspection and execution\n' +
         '  Discovery: --list, --search, --describe\n' +
         '  Execution: case-insensitive (network.getcookies works)')

package/dist/commands/cleanup.js

@@ -136,6 +136,9 @@ async function cleanupBlocker(opts) {
 }
 /**
  * Clean up the selected session (and delete its directory with `--purge`).
+ * It does not run the session directory trust check (`secureSessionDir`): it
+ * sends no command, only probes the socket and signals PIDs verified by
+ * their command line, and must still clean up an untrusted directory.
  *
  * @param opts - Cleanup options
  * @returns Command result

package/dist/commands/dom/eval.d.ts

@@ -11,7 +11,8 @@ import type { DomEvalCommandOptions } from '../shared/optionTypes.js';
  * frame the script ran in is a `Frame:` line on stderr (JSON: `frame`), and
  * a warning about how the result was copied goes there too (JSON:
  * `warning`), so stdout stays the bare value for pipes. Long values are cut
- * (a string result in JSON with `truncatedFrom`) unless `--full`.
+ * unless `--full`: human output when formatted, JSON results by
+ * {@link boundEvalResult}.
  */
 export declare function handleDomEval(script: string, options: DomEvalCommandOptions): Promise<void>;
 //# sourceMappingURL=eval.d.ts.map

package/dist/commands/dom/eval.js

@@ -5,21 +5,21 @@
  * CLI-side handler. Actual evaluation happens in the daemon via the
  * `dom_eval` IPC command so the session's persistent CDP connection is reused.
  */
+import { boundEvalResult } from './helpers/evalResult.js';
 import { documentReadyState } from './helpers/query.js';
 import { runCommand } from '../shared/CommandRunner.js';
-import { MAX_VALUE_LENGTH } from '../../constants.js';
 import { emptyScriptError, withLoadingHint } from '../../errors/messages.js';
 import { domEval } from '../../ipc/client.js';
 import { formatDomEval } from '../../ui/formatters/dom.js';
 import { evalFrameLine, warningMessage } from '../../ui/messages/commands.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
-import { capLength } from '../../utils/strings.js';
 /**
  * Handle `bdg dom eval <script> [--frame <frame>]`. With `--frame`, the
  * frame the script ran in is a `Frame:` line on stderr (JSON: `frame`), and
  * a warning about how the result was copied goes there too (JSON:
  * `warning`), so stdout stays the bare value for pipes. Long values are cut
- * (a string result in JSON with `truncatedFrom`) unless `--full`.
+ * unless `--full`: human output when formatted, JSON results by
+ * {@link boundEvalResult}.
  */
 export async function handleDomEval(script, options) {
     await runCommand(async () => {
@@ -32,7 +32,7 @@ export async function handleDomEval(script, options) {
                 errorContext: { suggestion: err.suggestion },
             };
         }
-        const response = await domEval(script, options.frame);
+        const response = await domEval(script, options.frame, options.full);
         if (response.status === 'error' || !response.data) {
             const suggestion = await frameErrorSuggestion(response, options.frame);
             return {
@@ -42,7 +42,7 @@ export async function handleDomEval(script, options) {
                 ...(suggestion && { errorContext: { suggestion } }),
             };
         }
-        const { value, type, subtype, frame, warning } = response.data;
+        const { value, type, subtype, length, frame, warning } = response.data;
         const hint = [
             ...(frame !== undefined ? [evalFrameLine(frame)] : []),
             ...(warning ? [warningMessage(warning)] : []),
@@ -50,7 +50,7 @@ export async function handleDomEval(script, options) {
         return {
             success: true,
             data: {
-                ...jsonResult(value, options),
+                ...(options.json && !options.full ? boundEvalResult(value, length) : { result: value }),
                 type,
                 ...(subtype && { subtype }),
                 ...(frame !== undefined && { frame }),
@@ -60,21 +60,6 @@ export async function handleDomEval(script, options) {
         };
     }, options, (data) => formatDomEval(data, { full: options.full }));
 }
-/**
- * The result field of the output: a string result in JSON cut to
- * {@link MAX_VALUE_LENGTH} characters with `truncatedFrom`, unless `--full`
- * (human output is cut when formatted).
- *
- * @param value - Evaluated value
- * @param options - `--json`, `--full`
- * @returns `result`, and `truncatedFrom` when cut
- */
-function jsonResult(value, options) {
-    if (!options.json || options.full || typeof value !== 'string')
-        return { result: value };
-    const { text, truncatedFrom } = capLength(value, MAX_VALUE_LENGTH);
-    return { result: text, ...(truncatedFrom !== undefined && { truncatedFrom }) };
-}
 /**
  * Suggestion of a failed eval; a frame not found (83) while the page is
  * still loading says so (its iframes may not exist yet).

package/dist/commands/dom/helpers/evalResult.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Bounds of a `dom eval --json` result (#478): one eval must not put
+ * megabytes into an agent's context.
+ */
+/**
+ * The `result` of `dom eval --json`, and what was left out of it. A string
+ * `result` with `truncatedFrom` while `type` is `object` is the start of
+ * the value's JSON text, not a string the script returned.
+ */
+export interface BoundedEvalResult {
+    /** The value, its first elements, or the start of its (JSON) text */
+    result: unknown;
+    /** Elements of an array result in the page, set only when it was bounded */
+    count?: number;
+    /** Elements left out of a listed array result */
+    omitted?: number;
+    /**
+     * Length of the string, or of the JSON text of the copied object or array
+     * (which holds at most 1000 entries per list or object), `result` was cut from
+     */
+    truncatedFrom?: number;
+}
+/**
+ * Bound an eval result for JSON output: a string is cut to
+ * {@link MAX_VALUE_LENGTH} characters, an array keeps its first
+ * {@link EVAL_JSON_ARRAY_LIMIT} elements (with `count` and `omitted`), and
+ * an object or array whose JSON is still longer than the cap becomes the
+ * start of its JSON text (with `truncatedFrom`), so the output stays valid
+ * JSON. Small values are returned as they are.
+ *
+ * @param value - Evaluated value, as copied from the page
+ * @param length - Elements of an array result in the page (its copy may hold fewer)
+ * @returns `result`, with what was left out when bounded
+ */
+export declare function boundEvalResult(value: unknown, length?: number): BoundedEvalResult;
+//# sourceMappingURL=evalResult.d.ts.map

package/dist/commands/dom/helpers/evalResult.js

@@ -0,0 +1,59 @@
+/**
+ * Bounds of a `dom eval --json` result (#478): one eval must not put
+ * megabytes into an agent's context.
+ */
+import { EVAL_JSON_ARRAY_LIMIT, MAX_VALUE_LENGTH } from '../../../constants.js';
+import { capLength } from '../../../utils/strings.js';
+/**
+ * Bound an eval result for JSON output: a string is cut to
+ * {@link MAX_VALUE_LENGTH} characters, an array keeps its first
+ * {@link EVAL_JSON_ARRAY_LIMIT} elements (with `count` and `omitted`), and
+ * an object or array whose JSON is still longer than the cap becomes the
+ * start of its JSON text (with `truncatedFrom`), so the output stays valid
+ * JSON. Small values are returned as they are.
+ *
+ * @param value - Evaluated value, as copied from the page
+ * @param length - Elements of an array result in the page (its copy may hold fewer)
+ * @returns `result`, with what was left out when bounded
+ */
+export function boundEvalResult(value, length) {
+    if (typeof value === 'string') {
+        const { text, truncatedFrom } = capLength(value, MAX_VALUE_LENGTH);
+        return { result: text, ...(truncatedFrom !== undefined && { truncatedFrom }) };
+    }
+    if (Array.isArray(value))
+        return boundArray(value, length ?? value.length);
+    if (value === null || typeof value !== 'object')
+        return { result: value };
+    const json = JSON.stringify(value);
+    return json.length > MAX_VALUE_LENGTH ? jsonStart(json) : { result: value };
+}
+/**
+ * Bound an array result: its first {@link EVAL_JSON_ARRAY_LIMIT} elements,
+ * or the start of its JSON text when even those are over the cap.
+ *
+ * @param value - Array result
+ * @param count - Elements of the array in the page
+ * @returns `result` with `count`, and `omitted` or `truncatedFrom`
+ */
+function boundArray(value, count) {
+    const listed = value.slice(0, EVAL_JSON_ARRAY_LIMIT);
+    const listedJson = JSON.stringify(listed);
+    if (listedJson.length > MAX_VALUE_LENGTH) {
+        const json = listed.length === value.length ? listedJson : JSON.stringify(value);
+        return { ...jsonStart(json), count };
+    }
+    return listed.length < count
+        ? { result: listed, count, omitted: count - listed.length }
+        : { result: value };
+}
+/**
+ * The first {@link MAX_VALUE_LENGTH} characters of a JSON text.
+ *
+ * @param json - JSON text of an object or array over the cap
+ * @returns Its start, and the length of all of it
+ */
+function jsonStart(json) {
+    return { result: capLength(json, MAX_VALUE_LENGTH).text, truncatedFrom: json.length };
+}
+//# sourceMappingURL=evalResult.js.map

package/dist/commands/helpJson.d.ts

@@ -93,7 +93,7 @@ export interface CompactCommand {
     name: string;
     /** Command aliases (only when it has some) */
     aliases?: readonly string[];
-    /** First line of the description */
+    /** Summary if set, else the first line of the description */
     description: string;
     /** Arguments as in usage, e.g. "<selector> [index]" (only when it takes some) */
     arguments?: string;

package/dist/commands/helpJson.js

@@ -114,8 +114,8 @@ function argumentTerm(argument) {
     return argument.required ? `<${name}>` : `[${name}]`;
 }
 /**
- * Recursively converts a Commander Command to its compact summary: first
- * description line, arguments, and visible options with their descriptions.
+ * Recursively converts a Commander Command to its compact summary: summary
+ * (or first description line), arguments, and visible options with their descriptions.
  * Empty fields are left out.
  *
  * @param command - Commander command instance
@@ -128,7 +128,7 @@ function convertCompactCommand(command) {
     return {
         name: command.name(),
         ...(aliases.length > 0 && { aliases }),
-        description: command.description().split('\n')[0] ?? '',
+        description: command.summary() || (command.description().split('\n')[0] ?? ''),
         ...(args && { arguments: args }),
         ...(options.length > 0 && {
             options: Object.fromEntries(options.map((option) => [option.flags, option.description])),

package/dist/commands/helpTopic.js

@@ -3,11 +3,14 @@
  */
 import { commandPath } from './helpJson.js';
 import { CommandError } from '../errors/index.js';
-import { missingSubcommandMessage, unknownHelpTopicError, usageHelpSuggestion, } from '../errors/messages.js';
+import { didYouMeanSuggestion, missingSubcommandMessage, unknownHelpTopicError, usageHelpSuggestion, } from '../errors/messages.js';
 import { EXIT_CODES } from '../utils/exitCodes.js';
 import { findSimilar } from '../utils/suggestions.js';
-/** Commander's typo hint on its own line, e.g. "(Did you mean query?)" */
-const COMMANDER_HINT = /\n?\(Did you mean (.+)\?\)\s*$/;
+/**
+ * Commander's typo hint on its own line: "(Did you mean query?)" or, for
+ * several equally close candidates, "(Did you mean one of form, frames?)"
+ */
+const COMMANDER_HINT = /\n?\(Did you mean (?:one of )?(.+)\?\)\s*$/;
 /**
  * The command path of `bdg help <path...>`: the words before the first option.
  *
@@ -54,7 +57,10 @@ export function splitCommanderHint(text) {
     const hint = COMMANDER_HINT.exec(message);
     if (!hint)
         return { message };
-    return { message: message.slice(0, hint.index).trim(), suggestion: `Did you mean: ${hint[1]}?` };
+    return {
+        message: message.slice(0, hint.index).trim(),
+        suggestion: didYouMeanSuggestion((hint[1] ?? '').split(', ')),
+    };
 }
 /** The option named in Commander's "unknown option '--x'" message, without an `=value` */
 const UNKNOWN_OPTION = /unknown option '([^'=]+)/;

package/dist/commands/network/har.js

@@ -15,6 +15,7 @@ import { getSessionFilePath } from '../../session/paths.js';
 import { applyFilters, parseFilterString } from '../../telemetry/filterDsl.js';
 import { buildHAR } from '../../telemetry/har/builder.js';
 import { createLogger } from '../../ui/logging/index.js';
+import { harExportedMessage } from '../../ui/messages/networkMessages.js';
 import { getErrorMessage } from '../../utils/errors.js';
 import { VERSION } from '../../utils/version.js';
 import { getNetworkRequests, validateFilterOption } from './shared.js';
@@ -67,15 +68,20 @@ async function getChromeVersion() {
 function formatHARExport(data) {
     if ('log' in data)
         return JSON.stringify(data, null, 2);
-    const filterNote = data.filtered ? ' (filtered)' : '';
-    return `✓ Exported ${data.entries} requests${filterNote} to ${data.file}`;
+    return harExportedMessage(data);
 }
+/** HAR files may hold credentials (--include-sensitive): readable by their owner only */
+const HAR_FILE_MODE = 0o600;
 /** Output path meaning "write the HAR to stdout" */
 const STDOUT_PATH = '-';
 /**
  * Option for filter DSL.
  */
 const filterDslOption = new Option('--filter <dsl>', 'Filter requests using DevTools DSL (e.g., "status-code:>=400")');
+/**
+ * Option to keep credentials in the export.
+ */
+const includeSensitiveOption = new Option('--include-sensitive', 'Keep credentials (auth/cookie/API key headers, cookie values, URL tokens, password and token body fields); redacted by default');
 /**
  * Register HAR export command.
  *
@@ -88,6 +94,7 @@ export function registerHarCommand(networkCmd) {
         .description('Export network data as HAR 1.2 format')
         .addOption(jsonOption())
         .addOption(filterDslOption)
+        .addOption(includeSensitiveOption)
         .action(async (outputFile, options) => {
         await runCommand(async () => {
             let requests = await getNetworkRequests();
@@ -103,21 +110,18 @@ export function registerHarCommand(networkCmd) {
             if (outputPath !== STDOUT_PATH)
                 assertFilePath(outputPath, '.har');
             const chromeVersion = await getChromeVersion();
-            const har = buildHAR(requests, {
-                version: VERSION,
-                ...(chromeVersion && { chromeVersion }),
-            });
+            const includeSensitive = options.includeSensitive === true;
+            const har = buildHAR(requests, { version: VERSION, ...(chromeVersion && { chromeVersion }) }, { includeSensitive });
             if (outputPath === STDOUT_PATH)
                 return { success: true, data: har };
-            const file = await writeOutputFile(outputPath, JSON.stringify(har, null, 2), '.har');
-            return {
-                success: true,
-                data: {
-                    file,
-                    entries: har.log.entries.length,
-                    filtered,
-                },
+            const file = await writeOutputFile(outputPath, JSON.stringify(har, null, 2), '.har', HAR_FILE_MODE);
+            const data = {
+                file,
+                entries: har.log.entries.length,
+                filtered,
+                sanitized: !includeSensitive,
             };
+            return { success: true, data };
         }, options, formatHARExport);
     });
 }

package/dist/commands/optionBehaviors.js

@@ -101,9 +101,9 @@ const OPTION_BEHAVIORS = {
         automaticBehavior: 'The value is matched as: a 0-based index (bdg dom frames order: document order of the <iframe> elements, nested ones depth-first, main page not counted), else an exact name/id attribute, else a case-insensitive part of the name, id or URL. Several matches fail with 81 listing them; none fails with 83 listing all frames. Frames are looked up on every call (a reloaded iframe is found again). An index that names another frame than in the last bdg dom frames listing (iframes added, removed or moved, or the page navigated) fails with 87 STALE_CACHE: re-run bdg dom frames or pick the frame by name.',
     },
     'eval:--full': {
-        default: 'Human output prints the first 20000 characters of the value followed by "… N more chars (use --full)"; in JSON a string result is cut to 20000 characters with truncatedFrom (the original length). Objects and arrays in JSON are not cut',
-        whenEnabled: 'Prints the whole value, byte for byte',
-        tokenImpact: 'dom eval document.documentElement.outerHTML on Wikipedia is about 3.6 MB with --full; select what you need in the expression instead',
+        default: 'Human output prints the first 20000 characters of the value followed by "… N more chars (use --full)". In JSON a string result is cut to 20000 characters with truncatedFrom (the original length); an array result lists its first 100 elements with count (all of them) and omitted; an object or array whose JSON is still over 20000 characters becomes the first 20000 characters of its JSON text (a string; arrays keep count) with truncatedFrom (the length of the JSON text of the copy, which holds at most 1000 entries per list or object): a string result with truncatedFrom while type is object is such a JSON-text start',
+        whenEnabled: 'Prints the whole value, byte for byte; objects and arrays are copied with every entry (without --full at most 1000 per list or object)',
+        tokenImpact: 'dom eval document.documentElement.outerHTML on Wikipedia is about 3.6 MB with --full; on a page with 20000 elements, [...document.querySelectorAll("*")].map(e => e.outerHTML) --json is 3 MB with --full and 23 KB without; select what you need in the expression instead',
     },
     'console:--full': {
         default: 'Message texts are cut: human output (summary, --list, --follow) at 200 characters followed by "… N more chars (use --full)"; JSON text at 10000 characters with truncatedFrom (the original length)',
@@ -330,6 +330,11 @@ const OPTION_BEHAVIORS = {
         whenEnabled: 'Streams requests as they finish',
         automaticBehavior: FOLLOW_BEHAVIOR,
     },
+    'har:--include-sensitive': {
+        default: 'The HAR is sanitized: values become "[redacted]" for Authorization, Proxy-Authorization, Authentication, Cookie and Set-Cookie headers, X-*key/token/secret/auth headers and headers with an api-key/apikey/token/secret/jwt/subscription-key/session(-id) segment (www-authenticate is kept); every cookie value; query and fragment parameters named like credentials (plus code, sig, key) in the request URL, queryString, redirectURL and Location/Referer headers ("%5Bredacted%5D" in URLs); and password/token/secret/key/session/signature fields of JSON (primitives at any depth under such a name), form-urlencoded (also sniffed when the Content-Type says otherwise) and multipart request bodies. A JSON body too deep to walk becomes "[redacted]" whole. Header, cookie and parameter names, cookie attributes, headersSize and bodySize stay; log.comment and JSON sanitized: true say so',
+        whenEnabled: 'Writes every captured value (JSON sanitized: false); human output warns that the file holds credentials',
+        automaticBehavior: 'Matching is by name, so it over-redacts: harmless values under credential-looking names (tokenCount: 5, sessionLength) are replaced too, and credentials under other names are kept. Unlike Chrome DevTools, which drops these headers and empties cookies, names are kept so the HAR still shows a request was authenticated. Response bodies and WebSocket messages are not redacted. HAR files are written readable by their owner only (0600). network headers and network getCookies always show real values',
+    },
     'peek:--verbose': {
         default: 'Compact output (truncated URLs, no resource types)',
         whenEnabled: 'Verbose output with full URLs and resource types',

package/dist/commands/shared/optionTypes.d.ts

@@ -300,6 +300,7 @@ export type NetworkCookiesCommandOptions = BaseOptions & {
 /** Options for network HAR command */
 export type NetworkHarCommandOptions = BaseOptions & {
     outputFile?: string;
+    includeSensitive?: boolean;
 };
 /** Options for network headers command */
 export type NetworkHeadersCommandOptions = BaseOptions & {

package/dist/commands/shared/outputFile.d.ts

@@ -26,8 +26,9 @@ export declare function assertFilePath(filePath: string, extension?: string): vo
  * @param filePath - Path the user gave
  * @param data - File contents
  * @param extension - Extension of the file kind, for examples in errors
+ * @param mode - File permissions of a text file (default: 0666 less the umask)
  * @returns Absolute path written
  * @throws CommandError naming the path when it cannot be written
  */
-export declare function writeOutputFile(filePath: string, data: string | Buffer, extension?: string): Promise<string>;
+export declare function writeOutputFile(filePath: string, data: string | Buffer, extension?: string, mode?: number): Promise<string>;
 //# sourceMappingURL=outputFile.d.ts.map

package/dist/commands/shared/outputFile.js

@@ -62,18 +62,21 @@ export function assertFilePath(filePath, extension) {
  * @param filePath - Path the user gave
  * @param data - File contents
  * @param extension - Extension of the file kind, for examples in errors
+ * @param mode - File permissions of a text file (default: 0666 less the umask)
  * @returns Absolute path written
  * @throws CommandError naming the path when it cannot be written
  */
-export async function writeOutputFile(filePath, data, extension) {
+export async function writeOutputFile(filePath, data, extension, mode) {
     assertFilePath(filePath, extension);
     const absolutePath = path.resolve(filePath);
     try {
         makeDirectory(path.dirname(absolutePath));
-        if (typeof data === 'string')
-            await AtomicFileWriter.writeAsync(absolutePath, data);
-        else
+        if (typeof data === 'string') {
+            await AtomicFileWriter.writeAsync(absolutePath, data, mode === undefined ? {} : { mode });
+        }
+        else {
             await AtomicFileWriter.writeBufferAsync(absolutePath, data);
+        }
     }
     catch (error) {
         throw outputPathError(filePath, error, extension);

package/dist/commands/status.js

@@ -1,5 +1,5 @@
 import { runCommand } from './shared/CommandRunner.js';
-import { isDaemonConnectionError } from '../errors/index.js';
+import { CommandError, isDaemonConnectionError } from '../errors/index.js';
 import { invalidResponseError, sessionNotRespondingError } from '../errors/messages.js';
 import { getStatus } from '../ipc/client.js';
 import { IPCTimeoutError } from '../ipc/transport/IPCError.js';
@@ -134,6 +134,8 @@ export function registerStatusCommand(program) {
                 return { success: true, data: withSessionName(jsonOutput) };
             }
             catch (error) {
+                if (error instanceof CommandError)
+                    throw error;
                 const errorMessage = getErrorMessage(error);
                 if (error instanceof IPCTimeoutError) {
                     const err = sessionNotRespondingError(error.timeoutMs / 1000);

package/dist/commands/stop.js

@@ -1,5 +1,6 @@
 import { runCommand } from './shared/CommandRunner.js';
 import { jsonOption } from './shared/commonOptions.js';
+import { CommandError } from '../errors/index.js';
 import { stopSession } from '../ipc/client.js';
 import { IPCErrorCode } from '../ipc/index.js';
 import { IPCTimeoutError } from '../ipc/transport/index.js';
@@ -97,7 +98,7 @@ export function registerStopCommand(program) {
                 }
             }
             catch (error) {
-                if (error instanceof IPCTimeoutError)
+                if (error instanceof IPCTimeoutError || error instanceof CommandError)
                     throw error;
                 const errorMessage = getErrorMessage(error);
                 if (isDaemonNotRunningError(errorMessage)) {

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

@@ -56,5 +56,51 @@ export declare function needsNoSandbox(): boolean;
  * @returns True if running in Docker, false otherwise
  */
 export declare function isDocker(): boolean;
+/**
+ * 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 declare function dropLauncherHeadlessEnv(env?: NodeJS.ProcessEnv): void;
+/**
+ * Build Chrome flags array from launch options.
+ *
+ * Uses chrome-launcher default flags as base (unless ignoreDefaultFlags is true)
+ * and layers bdg-specific overrides on top. Headless mode uses the new headless
+ * implementation for better compatibility.
+ *
+ * When running in Docker, automatically adds GPU-disabling flags to work around
+ * graphics limitations in containerized environments.
+ *
+ * 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
+ *
+ * @example
+ * ```typescript
+ * // Standard flags
+ * const flags = buildChromeFlags({ port: 9222 });
+ *
+ * // Headless with custom flags
+ * const flags = buildChromeFlags({
+ *   port: 9222,
+ *   headless: true,
+ *   chromeFlags: ['--window-size=1920,1080']
+ * });
+ *
+ * // Docker environment (auto-detects)
+ * const flags = buildChromeFlags({ port: 9222 });
+ * // Includes --disable-gpu, --no-sandbox if in Docker
+ * ```
+ */
 export declare function buildChromeFlags(options: FlagsBuilderOptions): string[];
 //# sourceMappingURL=flagsBuilder.d.ts.map