browser-debugger-cli 0.7.1 → 0.8.0

package/dist/commands/network/har.js

@@ -7,21 +7,24 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { Option } from 'commander';
-import { runCommand } from '../../commands/shared/CommandRunner.js';
-import { jsonOption } from '../../commands/shared/commonOptions.js';
+import { runCommand } from '../shared/CommandRunner.js';
+import { jsonOption } from '../shared/commonOptions.js';
+import { assertFilePath, writeOutputFile } from '../shared/outputFile.js';
+import { callCDP } from '../../ipc/client.js';
 import { getSessionFilePath } from '../../session/paths.js';
-import { applyFilters, parseFilterString, validateFilterString } from '../../telemetry/filterDsl.js';
+import { applyFilters, parseFilterString } from '../../telemetry/filterDsl.js';
 import { buildHAR } from '../../telemetry/har/builder.js';
-import { CommandError } from '../../ui/errors/index.js';
-import { operationFailedError } from '../../ui/messages/errors.js';
-import { AtomicFileWriter } from '../../utils/atomicFile.js';
-import { EXIT_CODES } from '../../utils/exitCodes.js';
+import { createLogger } from '../../ui/logging/index.js';
+import { getErrorMessage } from '../../utils/errors.js';
 import { VERSION } from '../../utils/version.js';
-import { getNetworkRequests } from './shared.js';
+import { getNetworkRequests, validateFilterOption } from './shared.js';
+const log = createLogger('network');
 /**
  * Generate timestamped filename for HAR export in ~/.bdg/ directory.
  *
- * @returns Full path to HAR file in ~/.bdg/capture-YYYY-MM-DD-HHMMSS.har
+ * A numeric suffix is added when an export from the same second exists.
+ *
+ * @returns Full path to HAR file in ~/.bdg/capture-YYYY-MM-DD-HHMMSS[-n].har
  */
 function generateHARFilename() {
     const now = new Date();
@@ -31,20 +34,44 @@ function generateHARFilename() {
     const hours = String(now.getHours()).padStart(2, '0');
     const minutes = String(now.getMinutes()).padStart(2, '0');
     const seconds = String(now.getSeconds()).padStart(2, '0');
-    const filename = `capture-${year}-${month}-${day}-${hours}${minutes}${seconds}.har`;
+    const base = `capture-${year}-${month}-${day}-${hours}${minutes}${seconds}`;
     const sessionDir = path.dirname(getSessionFilePath('OUTPUT'));
-    return path.join(sessionDir, filename);
+    let candidate = path.join(sessionDir, `${base}.har`);
+    for (let n = 2; fs.existsSync(candidate); n++) {
+        candidate = path.join(sessionDir, `${base}-${n}.har`);
+    }
+    return candidate;
+}
+/**
+ * Chrome version of the session's browser, for the HAR `log.browser` field.
+ *
+ * @returns Version like "131.0.6778.86", or undefined if unavailable
+ */
+async function getChromeVersion() {
+    try {
+        const response = await callCDP('Browser.getVersion', {});
+        const product = response.data?.result?.product;
+        return product?.split('/')[1];
+    }
+    catch (error) {
+        log.debug(`Could not read Chrome version: ${getErrorMessage(error)}`);
+        return undefined;
+    }
 }
 /**
  * Format HAR export success message for human output.
  *
- * @param data - HAR export result data
- * @returns Formatted success message
+ * @param data - HAR export result data, or the HAR itself for `-` (stdout)
+ * @returns Formatted success message, or the HAR as JSON
  */
 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}`;
 }
+/** Output path meaning "write the HAR to stdout" */
+const STDOUT_PATH = '-';
 /**
  * Option for filter DSL.
  */
@@ -57,6 +84,7 @@ const filterDslOption = new Option('--filter <dsl>', 'Filter requests using DevT
 export function registerHarCommand(networkCmd) {
     networkCmd
         .command('har [output-file]')
+        .addHelpText('after', '\nUse - as the output file to write the HAR to stdout.')
         .description('Export network data as HAR 1.2 format')
         .addOption(jsonOption())
         .addOption(filterDslOption)
@@ -65,29 +93,27 @@ export function registerHarCommand(networkCmd) {
             let requests = await getNetworkRequests();
             let filtered = false;
             if (options.filter) {
-                const validation = validateFilterString(options.filter);
-                if (!validation.valid) {
-                    const err = operationFailedError('validate filter', validation.suggestion ?? 'Check filter syntax');
-                    throw new CommandError(validation.error, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
-                }
+                validateFilterOption(options.filter);
                 const filters = parseFilterString(options.filter);
                 const originalCount = requests.length;
                 requests = applyFilters(requests, filters);
                 filtered = requests.length !== originalCount;
             }
             const outputPath = outputFile ?? generateHARFilename();
-            const dir = path.dirname(outputPath);
-            if (dir !== '.' && !fs.existsSync(dir)) {
-                fs.mkdirSync(dir, { recursive: true });
-            }
+            if (outputPath !== STDOUT_PATH)
+                assertFilePath(outputPath, '.har');
+            const chromeVersion = await getChromeVersion();
             const har = buildHAR(requests, {
                 version: VERSION,
+                ...(chromeVersion && { chromeVersion }),
             });
-            await AtomicFileWriter.writeAsync(outputPath, JSON.stringify(har, null, 2));
+            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: outputPath,
+                    file,
                     entries: har.log.entries.length,
                     filtered,
                 },

package/dist/commands/network/list.js

@@ -2,27 +2,26 @@
  * Network list command with DevTools-compatible filter DSL.
  */
 import { Option } from 'commander';
-import { runCommand } from '../../commands/shared/CommandRunner.js';
-import { jsonOption } from '../../commands/shared/commonOptions.js';
-import { handleDaemonConnectionError } from '../../commands/shared/daemonErrorHandler.js';
-import { fetchNetworkRequests, createErrorResult } from '../../commands/shared/dataFetcher.js';
-import { setupFollowMode } from '../../commands/shared/followMode.js';
-import { positiveIntRule, resourceTypeRule } from '../../commands/shared/validation.js';
+import { runCommand } from '../shared/CommandRunner.js';
+import { jsonOption } from '../shared/commonOptions.js';
+import { handleDaemonConnectionError, noteFollowConnected, } from '../shared/daemonErrorHandler.js';
+import { fetchNetworkRequests, createErrorResult } from '../shared/dataFetcher.js';
+import { setupFollowMode } from '../shared/followMode.js';
+import { handleValidationError } from '../shared/handleValidationError.js';
+import { positiveIntRule, resourceTypeRule } from '../shared/validation.js';
 import { applyFilters, getFilterHelpText, validateFilterString } from '../../telemetry/filterDsl.js';
 import { resolvePreset, FILTER_PRESETS } from '../../telemetry/filterPresets.js';
 import { filterByResourceType } from '../../telemetry/filters.js';
-import { OutputBuilder } from '../../ui/OutputBuilder.js';
-import { CommandError } from '../../ui/errors/index.js';
-import { formatNetworkList } from '../../ui/formatters/networkList.js';
-import { operationFailedError } from '../../ui/messages/errors.js';
+import { buildSuccessResponse } from '../../ui/OutputBuilder.js';
+import { formatNetworkFollowRows, formatNetworkList, } from '../../ui/formatters/networkList.js';
 import { followingNetworkMessage, stoppedFollowingNetworkMessage, } from '../../ui/messages/networkMessages.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
+import { validateFilterOption } from './shared.js';
 const MIN_LAST = 0;
 const MAX_LAST = 10000;
 const DEFAULT_LAST = 100;
-const FOLLOW_LIMIT = 50;
 const FOLLOW_INTERVAL = 1000;
-const networkLastOption = new Option('--last <n>', `Show last N requests (0 = all, default: ${DEFAULT_LAST})`).default(String(DEFAULT_LAST));
+const networkLastOption = new Option('--last <n>', 'Show last N requests (0 = all)').default(String(DEFAULT_LAST));
 /**
  * Validate preset option early with typo detection.
  *
@@ -45,11 +44,7 @@ function validateAndGetFilters(options) {
     const filterString = buildFilterString(options);
     if (!filterString)
         return;
-    const validation = validateFilterString(filterString);
-    if (!validation.valid) {
-        const err = operationFailedError('validate filter', validation.suggestion ?? 'Check filter syntax');
-        throw new CommandError(validation.error, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
-    }
+    validateFilterOption(filterString);
 }
 /**
  * Parse and validate resource types from --type option.
@@ -61,31 +56,23 @@ function parseResourceTypes(typeOption) {
     return resourceTypeRule().validate(typeOption);
 }
 /**
- * Handle validation errors with proper JSON/human formatting.
+ * Whether the active filters inspect headers, which the list only fetches on demand.
  *
- * @param error - Error from validation
- * @param json - Whether to output JSON format
+ * @param options - Command options
+ * @returns True when headers must be fetched for filtering
  */
-function handleValidationError(error, json) {
-    if (error instanceof CommandError) {
-        if (json) {
-            const errorOptions = {
-                exitCode: error.exitCode,
-            };
-            if (error.metadata.suggestion) {
-                errorOptions.suggestion = error.metadata.suggestion;
-            }
-            console.log(JSON.stringify(OutputBuilder.buildJsonError(error.message, errorOptions)));
-        }
-        else {
-            console.error(error.message);
-            if (error.metadata.suggestion)
-                console.error(error.metadata.suggestion);
-        }
-        process.exit(error.exitCode);
-    }
-    console.error(error instanceof Error ? error.message : String(error));
-    process.exit(EXIT_CODES.INVALID_ARGUMENTS);
+function filtersNeedHeaders(options) {
+    return /has-response-header:|is:from-cache/.test(buildFilterString(options));
+}
+/**
+ * Drop headers fetched only for filtering, keeping the list output unchanged.
+ *
+ * @param request - Request with headers
+ * @returns Request without request/response headers
+ */
+function withoutHeaders(request) {
+    const { requestHeaders: _requestHeaders, responseHeaders: _responseHeaders, ...rest } = request;
+    return rest;
 }
 /**
  * Filter requests using DSL filters and resource type filters.
@@ -107,20 +94,38 @@ function filterRequests(requests, options, resourceTypes) {
     if (resourceTypes.length > 0) {
         filtered = filterByResourceType(filtered, resourceTypes);
     }
-    return filtered;
+    return filtersNeedHeaders(options) ? filtered.map(withoutHeaders) : filtered;
 }
-function buildFormatOptions(options, totalCount, lastLimit, follow = false) {
+/**
+ * Formatter options for a listing.
+ *
+ * @param options - Command options
+ * @param result - Requests listed, with their counts
+ * @param lastLimit - The --last limit
+ * @returns Formatter options
+ */
+function buildFormatOptions(options, result, lastLimit) {
     return {
-        json: options.json ?? false,
         verbose: options.verbose ?? false,
         last: lastLimit,
-        totalCount,
-        follow,
+        totalCount: result.totalCount,
+        filteredCount: result.filteredCount,
     };
 }
-async function runFollowMode(options, resourceTypes) {
+/**
+ * Stream network requests: the last `lastN` finished ones at start, then
+ * each request once, when it has finished loading or failed (a request whose
+ * headers arrived but whose body is still loading waits), like `tail -f`.
+ *
+ * @param options - Command options
+ * @param resourceTypes - Validated resource types
+ * @param lastN - Requests to show at start (0 = all)
+ */
+async function runFollowMode(options, resourceTypes, lastN) {
+    const shown = new Set();
+    let started = false;
     const showNetwork = async () => {
-        const result = await fetchNetworkRequests();
+        const result = await fetchNetworkRequests(filtersNeedHeaders(options));
         if (!result.success) {
             const errorResult = handleDaemonConnectionError(result.error, {
                 json: options.json,
@@ -132,11 +137,33 @@ async function runFollowMode(options, resourceTypes) {
                 process.exit(errorResult.exitCode);
             return;
         }
-        const filtered = filterRequests(result.data, options, resourceTypes);
-        const displayRequests = filtered.slice(-FOLLOW_LIMIT);
-        const formatOptions = buildFormatOptions(options, filtered.length, FOLLOW_LIMIT, true);
-        console.clear();
-        console.log(formatNetworkList(displayRequests, formatOptions));
+        noteFollowConnected();
+        const finished = filterRequests(result.data, options, resourceTypes).filter((request) => request.duration !== undefined && !shown.has(request.requestId));
+        const present = new Set(result.data.map((request) => request.requestId));
+        for (const id of shown)
+            if (!present.has(id))
+                shown.delete(id);
+        finished.forEach((request) => shown.add(request.requestId));
+        const fresh = started || lastN === 0 ? finished : finished.slice(-lastN);
+        if (options.json) {
+            if (!started || fresh.length > 0) {
+                const data = {
+                    requests: fresh,
+                    totalCount: result.data.length,
+                    filteredCount: fresh.length,
+                };
+                console.log(JSON.stringify(buildSuccessResponse(data), null, 2));
+            }
+        }
+        else {
+            const text = formatNetworkFollowRows(fresh, {
+                header: !started,
+                verbose: options.verbose ?? false,
+            });
+            if (text)
+                console.log(text);
+        }
+        started = true;
     };
     await setupFollowMode(showNetwork, {
         startMessage: followingNetworkMessage,
@@ -155,7 +182,7 @@ export function registerListCommand(networkCmd) {
         .description('List network requests with DevTools-compatible filtering')
         .addOption(jsonOption())
         .addOption(new Option('--filter <dsl>', 'Filter requests using DevTools DSL (e.g., "status-code:>=400 domain:api.*")'))
-        .addOption(new Option('--preset <name>', 'Use predefined filter preset'))
+        .addOption(new Option('--preset <name>', `Use predefined filter preset: ${Object.keys(FILTER_PRESETS).join(', ')}`))
         .addOption(new Option('--type <types>', 'Filter by resource type (comma-separated: Document,XHR,Fetch,etc.)'))
         .addOption(networkLastOption)
         .addOption(new Option('-f, --follow', 'Stream network requests in real-time').default(false))
@@ -168,32 +195,38 @@ export function registerListCommand(networkCmd) {
             validatePreset(options.preset);
             validateAndGetFilters(options);
             resourceTypes = parseResourceTypes(options.type);
-            lastN = positiveIntRule({ min: MIN_LAST, max: MAX_LAST, default: DEFAULT_LAST }).validate(options.last);
+            lastN = positiveIntRule({
+                name: '--last',
+                min: MIN_LAST,
+                max: MAX_LAST,
+                default: DEFAULT_LAST,
+            }).validate(options.last);
         }
         catch (error) {
             handleValidationError(error, options.json ?? false);
         }
         if (options.follow) {
-            await runFollowMode(options, resourceTypes);
+            await runFollowMode(options, resourceTypes, lastN);
             return;
         }
         await runCommand(async () => {
-            const result = await fetchNetworkRequests();
+            const result = await fetchNetworkRequests(filtersNeedHeaders(options));
             if (!result.success) {
                 if (result.exitCode === EXIT_CODES.SUCCESS) {
-                    return { success: true, data: { requests: [], filtered: [], totalCount: 0 } };
+                    return { success: true, data: { requests: [], totalCount: 0, filteredCount: 0 } };
                 }
-                return createErrorResult(result.error, result.exitCode);
+                return createErrorResult(result.error, result.exitCode, result.suggestion);
             }
             const filtered = filterRequests(result.data, options, resourceTypes);
             return {
                 success: true,
-                data: { requests: result.data, filtered, totalCount: result.data.length },
+                data: {
+                    requests: lastN === 0 ? filtered : filtered.slice(-lastN),
+                    totalCount: result.data.length,
+                    filteredCount: filtered.length,
+                },
             };
-        }, options, (data) => {
-            const displayRequests = lastN === 0 ? data.filtered : data.filtered.slice(-lastN);
-            return formatNetworkList(displayRequests, buildFormatOptions(options, data.totalCount, lastN));
-        });
+        }, options, (data) => formatNetworkList(data.requests, buildFormatOptions(options, data, lastN)));
     });
 }
 //# sourceMappingURL=list.js.map

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

@@ -13,28 +13,22 @@ import type { NetworkRequest } from '../../types.js';
  */
 export declare function fetchFromLiveSession(): Promise<NetworkRequest[]>;
 /**
- * Fetch network requests from offline session.json file.
+ * Get network requests from live daemon session.
  *
  * @returns Network requests array
- * @throws Error if session file not found or no network data available
- */
-export declare function fetchFromOfflineSession(): NetworkRequest[];
-/**
- * Check if error indicates daemon is unavailable.
- *
- * @param error - Error to check
- * @returns True if error indicates no active session or daemon connection failure
+ * @throws Error if daemon connection fails or no network data available
  */
-export declare function isDaemonUnavailable(error: unknown): boolean;
+export declare function getNetworkRequests(): Promise<NetworkRequest[]>;
 /**
- * Get network requests from live session or session.json.
+ * Validate a filter DSL string and throw a CommandError on invalid input.
  *
- * Tries live daemon first, falls back to offline session file.
+ * Centralises the parse-validate-throw flow used by network commands so each
+ * command site stays a single line.
  *
- * @returns Network requests array
- * @throws Error if no session available (live or offline)
+ * @param filterString - Filter DSL string to validate
+ * @throws CommandError with INVALID_ARGUMENTS exit code on invalid syntax
  */
-export declare function getNetworkRequests(): Promise<NetworkRequest[]>;
+export declare function validateFilterOption(filterString: string): void;
 /**
  * Register getCookies command.
  *

package/dist/commands/network/shared.js

@@ -3,15 +3,14 @@
  *
  * Contains getCookies and headers commands, plus shared data fetching utilities.
  */
-import * as fs from 'fs';
-import { runCommand } from '../../commands/shared/CommandRunner.js';
-import { jsonOption } from '../../commands/shared/commonOptions.js';
+import { runCommand } from '../shared/CommandRunner.js';
+import { jsonOption } from '../shared/commonOptions.js';
+import { CommandError } from '../../errors/index.js';
+import { operationFailedError } from '../../errors/messages.js';
 import { getHARData, callCDP, getNetworkHeaders } from '../../ipc/client.js';
 import { validateIPCResponse } from '../../ipc/index.js';
-import { getSessionFilePath } from '../../session/paths.js';
-import { isDaemonConnectionError } from '../../ui/errors/utils.js';
+import { validateFilterString } from '../../telemetry/filterDsl.js';
 import { formatCookies, formatNetworkHeaders } from '../../ui/formatters/index.js';
-import { sessionNotActiveError } from '../../ui/messages/errors.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
 /**
  * Fetch network requests from live daemon session.
@@ -28,57 +27,29 @@ export async function fetchFromLiveSession() {
     return response.data.requests;
 }
 /**
- * Fetch network requests from offline session.json file.
+ * Get network requests from live daemon session.
  *
  * @returns Network requests array
- * @throws Error if session file not found or no network data available
- */
-export function fetchFromOfflineSession() {
-    const sessionPath = getSessionFilePath('OUTPUT');
-    if (!fs.existsSync(sessionPath)) {
-        throw new Error(sessionNotActiveError('export network data'), {
-            cause: { code: EXIT_CODES.RESOURCE_NOT_FOUND },
-        });
-    }
-    const sessionData = JSON.parse(fs.readFileSync(sessionPath, 'utf-8'));
-    if (!sessionData.data?.network) {
-        throw new Error('No network data in session file', {
-            cause: { code: EXIT_CODES.RESOURCE_NOT_FOUND },
-        });
-    }
-    return sessionData.data.network;
-}
-/**
- * Check if error indicates daemon is unavailable.
- *
- * @param error - Error to check
- * @returns True if error indicates no active session or daemon connection failure
+ * @throws Error if daemon connection fails or no network data available
  */
-export function isDaemonUnavailable(error) {
-    if (isDaemonConnectionError(error)) {
-        return true;
-    }
-    const errorMessage = error instanceof Error ? error.message : String(error);
-    return errorMessage.includes('No active session');
+export async function getNetworkRequests() {
+    return fetchFromLiveSession();
 }
 /**
- * Get network requests from live session or session.json.
+ * Validate a filter DSL string and throw a CommandError on invalid input.
  *
- * Tries live daemon first, falls back to offline session file.
+ * Centralises the parse-validate-throw flow used by network commands so each
+ * command site stays a single line.
  *
- * @returns Network requests array
- * @throws Error if no session available (live or offline)
+ * @param filterString - Filter DSL string to validate
+ * @throws CommandError with INVALID_ARGUMENTS exit code on invalid syntax
  */
-export async function getNetworkRequests() {
-    try {
-        return await fetchFromLiveSession();
-    }
-    catch (error) {
-        if (isDaemonUnavailable(error)) {
-            return fetchFromOfflineSession();
-        }
-        throw error;
-    }
+export function validateFilterOption(filterString) {
+    const validation = validateFilterString(filterString);
+    if (validation.valid)
+        return;
+    const err = operationFailedError('validate filter', validation.suggestion ?? 'Check filter syntax');
+    throw new CommandError(validation.error, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
 }
 /**
  * Register getCookies command.
@@ -95,6 +66,14 @@ export function registerGetCookiesCommand(networkCmd) {
         await runCommand(async (opts) => {
             const params = {};
             if (opts.url) {
+                if (!URL.canParse(opts.url)) {
+                    return {
+                        success: false,
+                        error: `Invalid --url: ${opts.url}`,
+                        exitCode: EXIT_CODES.INVALID_ARGUMENTS,
+                        errorContext: { suggestion: 'Give a full URL, e.g. --url https://example.com/' },
+                    };
+                }
                 params['urls'] = [opts.url];
             }
             const response = await callCDP('Network.getCookies', params);
@@ -129,7 +108,7 @@ export function registerHeadersCommand(networkCmd) {
             if (!response.data) {
                 return {
                     success: false,
-                    error: 'No data returned from worker',
+                    error: 'No data returned from the session',
                     exitCode: EXIT_CODES.RESOURCE_NOT_FOUND,
                     errorContext: {
                         suggestion: 'No network requests captured yet. Navigate to a page first.',
@@ -163,7 +142,7 @@ export function registerDocumentCommand(networkCmd) {
             if (!response.data) {
                 return {
                     success: false,
-                    error: 'No data returned from worker',
+                    error: 'No data returned from the session',
                     exitCode: EXIT_CODES.RESOURCE_NOT_FOUND,
                     errorContext: {
                         suggestion: 'No document request found. Navigate to a page first.',

package/dist/commands/optionBehaviors.d.ts

@@ -6,7 +6,7 @@
  *
  * @see docs/principles/SELF_DOCUMENTING_SYSTEMS.md
  */
-import type { OptionBehavior } from '../commands/helpJson.js';
+import type { OptionBehavior } from './helpJson.js';
 /**
  * Look up behavioral metadata for an option.
  *
@@ -15,12 +15,4 @@ import type { OptionBehavior } from '../commands/helpJson.js';
  * @returns Behavioral metadata if registered, undefined otherwise
  */
 export declare function getOptionBehavior(commandName: string, flags: string): OptionBehavior | undefined;
-/**
- * Check if an option has registered behavioral metadata.
- *
- * @param commandName - Name of the command containing the option
- * @param flags - Option flags string from Commander
- * @returns True if behavior metadata exists
- */
-export declare function hasOptionBehavior(commandName: string, flags: string): boolean;
 //# sourceMappingURL=optionBehaviors.d.ts.map