browser-debugger-cli 0.7.2 → 0.9.0

package/dist/commands/helpJson.d.ts

@@ -30,9 +30,11 @@ export interface OptionMetadata {
     flags: string;
     /** Option description */
     description: string;
-    /** Whether option is required */
+    /** Whether the option must be given (rare; most options are optional) */
     required: boolean;
-    /** Whether option has an optional value */
+    /** Whether the option takes a value (`--port <number>`) */
+    takesValue: boolean;
+    /** Whether the option's value may be omitted (`--flag [value]`) */
     optional: boolean;
     /** Default value if any */
     defaultValue?: unknown;

package/dist/commands/helpJson.js

@@ -2,12 +2,10 @@
  * Machine-readable help generation using Commander.js introspection API.
  */
 import { getAllDomainSummaries } from '../cdp/schema.js';
-import { getOptionBehavior } from '../commands/optionBehaviors.js';
-import { isDaemonRunning } from '../daemon/launcher.js';
-import { readPid } from '../session/pid.js';
+import { getOptionBehavior } from './optionBehaviors.js';
+import { readLiveDaemonPid } from '../session/cleanup/staleSession.js';
 import { getAllDecisionTrees } from '../utils/decisionTrees.js';
 import { EXIT_CODE_REGISTRY } from '../utils/exitCodes.js';
-import { isProcessAlive } from '../utils/process.js';
 import { getAllTaskMappings } from '../utils/taskMappings.js';
 /**
  * Converts a Commander Option to OptionMetadata.
@@ -24,7 +22,8 @@ function convertOption(option, commandName) {
     const metadata = {
         flags: option.flags,
         description: option.description,
-        required: option.required,
+        required: option.mandatory,
+        takesValue: option.required || option.optional,
         optional: option.optional,
     };
     if (option.defaultValue !== undefined) {
@@ -86,42 +85,23 @@ function convertCommand(command) {
         subcommands: command.commands.map(convertCommand),
     };
 }
-/**
- * Checks if a session is currently active.
- *
- * @returns True if session is active, false otherwise
- */
-function isSessionActive() {
-    const sessionPid = readPid();
-    if (sessionPid === null) {
-        return false;
-    }
-    return isProcessAlive(sessionPid);
-}
 /**
  * Generates runtime state information.
  *
- * Checks current daemon and session status to provide state-aware
- * command availability information.
+ * The daemon hosts exactly one session, so a live daemon means an active
+ * session. Uses daemon.pid verified by command line to keep help generation
+ * synchronous; nothing is signalled based on this.
  *
  * @returns Runtime state object
  */
 function generateRuntimeState() {
-    const daemonRunning = isDaemonRunning();
-    const sessionActive = isSessionActive();
-    const availableCommands = [];
-    if (!daemonRunning && !sessionActive) {
-        availableCommands.push('bdg <url>', 'cleanup', '--help', '--version');
-    }
-    else if (daemonRunning && sessionActive) {
-        availableCommands.push('peek', 'tail', 'details', 'dom', 'network', 'console', 'cdp', 'status', 'stop');
-    }
-    else if (daemonRunning && !sessionActive) {
-        availableCommands.push('bdg <url>', 'cleanup', 'status');
-    }
+    const sessionActive = readLiveDaemonPid() !== null;
+    const availableCommands = sessionActive
+        ? ['peek', 'tail', 'details', 'dom', 'network', 'console', 'cdp', 'status', 'sessions', 'stop']
+        : ['bdg <url>', 'sessions', 'cleanup', '--help', '--version'];
     return {
         sessionActive,
-        daemonRunning,
+        daemonRunning: sessionActive,
         availableCommands,
     };
 }

package/dist/commands/helpTopic.d.ts

@@ -0,0 +1,32 @@
+/**
+ * `bdg help <command...>` topics and Commander usage-error hints.
+ */
+import type { Command } from 'commander';
+/**
+ * The command path of `bdg help <path...>`: the words before the first option.
+ *
+ * @param args - Arguments after `help`
+ * @returns Command words, e.g. ['dom', 'query']
+ */
+export declare function helpTopicPath(args: string[]): string[];
+/**
+ * Reject `bdg help <topic>` for a command that does not exist (instead of
+ * showing the general help and exiting 0). Stops at a command without
+ * subcommands (further words are its arguments) and at `help` itself.
+ *
+ * @param program - Root command with all commands registered
+ * @param topic - Command path after `help`
+ * @throws CommandError (81) naming the unknown command
+ */
+export declare function assertKnownHelpTopic(program: Command, topic: string[]): void;
+/**
+ * Split Commander's error text into the message and a "did you mean" suggestion.
+ *
+ * @param text - Commander error message
+ * @returns Message without the hint, and the hint as a suggestion
+ */
+export declare function splitCommanderHint(text: string): {
+    message: string;
+    suggestion?: string;
+};
+//# sourceMappingURL=helpTopic.d.ts.map

package/dist/commands/helpTopic.js

@@ -0,0 +1,58 @@
+/**
+ * `bdg help <command...>` topics and Commander usage-error hints.
+ */
+import { CommandError } from '../errors/index.js';
+import { unknownHelpTopicError } 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*$/;
+/**
+ * The command path of `bdg help <path...>`: the words before the first option.
+ *
+ * @param args - Arguments after `help`
+ * @returns Command words, e.g. ['dom', 'query']
+ */
+export function helpTopicPath(args) {
+    const firstOption = args.findIndex((arg) => arg.startsWith('-'));
+    return firstOption === -1 ? args : args.slice(0, firstOption);
+}
+/**
+ * Reject `bdg help <topic>` for a command that does not exist (instead of
+ * showing the general help and exiting 0). Stops at a command without
+ * subcommands (further words are its arguments) and at `help` itself.
+ *
+ * @param program - Root command with all commands registered
+ * @param topic - Command path after `help`
+ * @throws CommandError (81) naming the unknown command
+ */
+export function assertKnownHelpTopic(program, topic) {
+    let command = program;
+    const path = [];
+    for (const word of topic) {
+        if (command.commands.length === 0 || word === 'help')
+            return;
+        const sub = command.commands.find((c) => c.name() === word || c.aliases().includes(word));
+        if (!sub) {
+            const [closest] = findSimilar(word, command.commands.map((c) => c.name()));
+            const err = unknownHelpTopicError([...path, word].join(' '), closest && [...path, closest].join(' '));
+            throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
+        }
+        path.push(sub.name());
+        command = sub;
+    }
+}
+/**
+ * Split Commander's error text into the message and a "did you mean" suggestion.
+ *
+ * @param text - Commander error message
+ * @returns Message without the hint, and the hint as a suggestion
+ */
+export function splitCommanderHint(text) {
+    const message = text.replace(/^error:\s*/i, '');
+    const hint = COMMANDER_HINT.exec(message);
+    if (!hint)
+        return { message };
+    return { message: message.slice(0, hint.index).trim(), suggestion: `Did you mean: ${hint[1]}?` };
+}
+//# sourceMappingURL=helpTopic.js.map

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 { noteFollowConnected } from '../shared/daemonErrorHandler.js';
+import { fetchNetworkRequests, createErrorResult } from '../shared/dataFetcher.js';
+import { followFetchFailure, 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,36 +94,69 @@ 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,
-                follow: true,
-                retryIntervalMs: FOLLOW_INTERVAL,
-                exitCode: result.exitCode,
+            return followFetchFailure(result, { json: options.json, retryIntervalMs: FOLLOW_INTERVAL });
+        }
+        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 (errorResult.shouldExit)
-                process.exit(errorResult.exitCode);
-            return;
+            if (text)
+                console.log(text);
         }
-        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));
+        started = true;
+        return undefined;
     };
     await setupFollowMode(showNetwork, {
         startMessage: followingNetworkMessage,
@@ -155,7 +175,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 +188,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.
  *