browser-debugger-cli 0.6.2 → 0.6.5

package/dist/commands/machineReadableHelp.d.ts

@@ -2,6 +2,8 @@
  * Machine-readable help generation using Commander.js introspection API.
  */
 import type { Command } from 'commander';
+import { type DecisionTree } from '../utils/decisionTrees.js';
+import { type TaskMapping } from '../utils/taskMappings.js';
 /**
  * Option metadata for machine-readable help.
  */
@@ -57,6 +59,36 @@ export interface CommandMetadata {
     /** Subcommands */
     subcommands: CommandMetadata[];
 }
+/**
+ * Runtime state information for dynamic command availability.
+ */
+export interface RuntimeState {
+    /** Whether a session is currently active */
+    sessionActive: boolean;
+    /** Whether the daemon is running */
+    daemonRunning: boolean;
+    /** Commands available in current state */
+    availableCommands: string[];
+}
+/**
+ * Tool capabilities summary for agent discovery.
+ */
+export interface Capabilities {
+    /** CDP protocol capabilities */
+    cdp: {
+        /** Number of CDP domains */
+        domains: number;
+        /** Number of CDP methods (approximate) */
+        methods: string;
+    };
+    /** High-level command capabilities */
+    highLevel: {
+        /** Number of high-level commands */
+        commands: number;
+        /** Domain coverage areas */
+        coverage: string[];
+    };
+}
 /**
  * Root machine-readable help structure.
  */
@@ -78,10 +110,26 @@ export interface MachineReadableHelp {
         /** Exit code description */
         description: string;
     }[];
+    /** Task-to-command mappings with CDP alternatives */
+    taskMappings: Record<string, TaskMapping>;
+    /** Current runtime state */
+    runtimeState: RuntimeState;
+    /** Intent-based decision trees */
+    decisionTrees: Record<string, DecisionTree>;
+    /** Tool capabilities summary */
+    capabilities: Capabilities;
 }
 /**
  * Generates machine-readable help from a Commander program.
  *
+ * Includes comprehensive metadata for agent discovery:
+ * - Command structure and options
+ * - Exit codes with semantic meanings
+ * - Task-to-command mappings with CDP alternatives
+ * - Runtime state and command availability
+ * - Intent-based decision trees
+ * - Capabilities summary
+ *
  * @param program - Commander program instance
  * @returns Machine-readable help structure
  *

package/dist/commands/machineReadableHelp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"machineReadableHelp.d.ts","sourceRoot":"","sources":["../../src/commands/machineReadableHelp.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAoB,MAAM,WAAW,CAAC;AAI3D;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,wCAAwC;IACxC,KAAK,EAAE,MAAM,CAAC;IACd,yBAAyB;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,iCAAiC;IACjC,QAAQ,EAAE,OAAO,CAAC;IAClB,2CAA2C;IAC3C,QAAQ,EAAE,OAAO,CAAC;IAClB,2BAA2B;IAC3B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,mCAAmC;IACnC,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,oCAAoC;IACpC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,oBAAoB;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,2BAA2B;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,mCAAmC;IACnC,QAAQ,EAAE,OAAO,CAAC;IAClB,+CAA+C;IAC/C,QAAQ,EAAE,OAAO,CAAC;IAClB,2BAA2B;IAC3B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,oCAAoC;IACpC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,sBAAsB;IACtB,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,0BAA0B;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,2BAA2B;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,wBAAwB;IACxB,SAAS,EAAE,gBAAgB,EAAE,CAAC;IAC9B,sBAAsB;IACtB,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,kBAAkB;IAClB,WAAW,EAAE,eAAe,EAAE,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,eAAe;IACf,IAAI,EAAE,MAAM,CAAC;IACb,kBAAkB;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,sBAAsB;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,4BAA4B;IAC5B,OAAO,EAAE,eAAe,CAAC;IACzB,8BAA8B;IAC9B,SAAS,EAAE;QACT,sBAAsB;QACtB,IAAI,EAAE,MAAM,CAAC;QACb,qBAAqB;QACrB,IAAI,EAAE,MAAM,CAAC;QACb,4BAA4B;QAC5B,WAAW,EAAE,MAAM,CAAC;KACrB,EAAE,CAAC;CACL;AAuDD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,OAAO,GAAG,mBAAmB,CAkEjF"}
+{"version":3,"file":"machineReadableHelp.d.ts","sourceRoot":"","sources":["../../src/commands/machineReadableHelp.ts"],"names":[],"mappings":"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"}

package/dist/commands/machineReadableHelp.js

@@ -1,7 +1,13 @@
 /**
  * Machine-readable help generation using Commander.js introspection API.
  */
+import { getAllDomainSummaries } from '../cdp/schema.js';
+import { isDaemonRunning } from '../daemon/launcher.js';
+import { readPid } from '../session/pid.js';
+import { getAllDecisionTrees } from '../utils/decisionTrees.js';
 import { filterDefined } from '../utils/objects.js';
+import { isProcessAlive } from '../utils/process.js';
+import { getAllTaskMappings } from '../utils/taskMappings.js';
 /**
  * Converts a Commander Option to OptionMetadata.
  *
@@ -52,9 +58,79 @@ 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.
+ *
+ * @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');
+    }
+    return {
+        sessionActive,
+        daemonRunning,
+        availableCommands,
+    };
+}
+/**
+ * Generates capabilities summary.
+ *
+ * Dynamically calculates CDP and high-level command capabilities
+ * from protocol schema and task mappings.
+ *
+ * @returns Capabilities object
+ */
+function generateCapabilities() {
+    const domainSummaries = getAllDomainSummaries();
+    const taskMappings = getAllTaskMappings();
+    const totalMethods = domainSummaries.reduce((sum, domain) => sum + domain.commandCount, 0);
+    return {
+        cdp: {
+            domains: domainSummaries.length,
+            methods: totalMethods.toString(),
+        },
+        highLevel: {
+            commands: Object.keys(taskMappings).length,
+            coverage: ['dom', 'network', 'console', 'session', 'monitoring'],
+        },
+    };
+}
 /**
  * Generates machine-readable help from a Commander program.
  *
+ * Includes comprehensive metadata for agent discovery:
+ * - Command structure and options
+ * - Exit codes with semantic meanings
+ * - Task-to-command mappings with CDP alternatives
+ * - Runtime state and command availability
+ * - Intent-based decision trees
+ * - Capabilities summary
+ *
  * @param program - Commander program instance
  * @returns Machine-readable help structure
  *
@@ -132,6 +208,10 @@ export function generateMachineReadableHelp(program) {
                 description: 'Inter-process communication error',
             },
         ],
+        taskMappings: getAllTaskMappings(),
+        runtimeState: generateRuntimeState(),
+        decisionTrees: getAllDecisionTrees(),
+        capabilities: generateCapabilities(),
     };
 }
 //# sourceMappingURL=machineReadableHelp.js.map

package/dist/commands/machineReadableHelp.js.map

@@ -1 +1 @@
-{"version":3,"file":"machineReadableHelp.js","sourceRoot":"","sources":["../../src/commands/machineReadableHelp.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAmFnD;;;;;GAKG;AACH,SAAS,aAAa,CAAC,MAAc;IACnC,OAAO,aAAa,CAAC;QACnB,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,YAAY,EAAE,MAAM,CAAC,YAAuB;QAC5C,uBAAuB,EAAE,MAAM,CAAC,uBAAuB;QACvD,OAAO,EAAE,MAAM,CAAC,UAAU;KAC3B,CAA8B,CAAC;AAClC,CAAC;AAED;;;;;GAKG;AACH,SAAS,eAAe,CAAC,QAAkB;IACzC,OAAO,aAAa,CAAC;QACnB,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE;QACrB,WAAW,EAAE,QAAQ,CAAC,WAAW;QACjC,QAAQ,EAAE,QAAQ,CAAC,QAAQ;QAC3B,QAAQ,EAAE,QAAQ,CAAC,QAAQ;QAC3B,YAAY,EAAE,QAAQ,CAAC,YAAuB;QAC9C,OAAO,EAAE,QAAQ,CAAC,UAAU;KAC7B,CAAgC,CAAC;AACpC,CAAC;AAED;;;;;GAKG;AACH,SAAS,cAAc,CAAC,OAAgB;IACtC,OAAO;QACL,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE;QACpB,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE;QAC1B,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE;QAClC,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE;QACtB,SAAS,EAAE,OAAO,CAAC,mBAAmB,CAAC,GAAG,CAAC,eAAe,CAAC;QAC3D,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC;QAC3C,WAAW,EAAE,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,cAAc,CAAC;KAClD,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,2BAA2B,CAAC,OAAgB;IAC1D,OAAO;QACL,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE;QACpB,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,IAAI,SAAS;QACvC,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE;QAClC,OAAO,EAAE,cAAc,CAAC,OAAO,CAAC;QAChC,SAAS,EAAE;YACT,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,kCAAkC,EAAE;YAC7E,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,iBAAiB,EAAE,WAAW,EAAE,iBAAiB,EAAE;YACpE;gBACE,IAAI,EAAE,EAAE;gBACR,IAAI,EAAE,aAAa;gBACnB,WAAW,EAAE,6BAA6B;aAC3C;YACD;gBACE,IAAI,EAAE,EAAE;gBACR,IAAI,EAAE,mBAAmB;gBACzB,WAAW,EAAE,2BAA2B;aACzC;YACD;gBACE,IAAI,EAAE,EAAE;gBACR,IAAI,EAAE,mBAAmB;gBACzB,WAAW,EAAE,0BAA0B;aACxC;YACD;gBACE,IAAI,EAAE,EAAE;gBACR,IAAI,EAAE,oBAAoB;gBAC1B,WAAW,EAAE,6BAA6B;aAC3C;YACD;gBACE,IAAI,EAAE,EAAE;gBACR,IAAI,EAAE,eAAe;gBACrB,WAAW,EAAE,8BAA8B;aAC5C;YACD;gBACE,IAAI,EAAE,EAAE;gBACR,IAAI,EAAE,yBAAyB;gBAC/B,WAAW,EAAE,0CAA0C;aACxD;YACD;gBACE,IAAI,EAAE,EAAE;gBACR,IAAI,EAAE,wBAAwB;gBAC9B,WAAW,EAAE,2BAA2B;aACzC;YACD;gBACE,IAAI,EAAE,GAAG;gBACT,IAAI,EAAE,uBAAuB;gBAC7B,WAAW,EAAE,iCAAiC;aAC/C;YACD;gBACE,IAAI,EAAE,GAAG;gBACT,IAAI,EAAE,wBAAwB;gBAC9B,WAAW,EAAE,+CAA+C;aAC7D;YACD;gBACE,IAAI,EAAE,GAAG;gBACT,IAAI,EAAE,aAAa;gBACnB,WAAW,EAAE,yBAAyB;aACvC;YACD;gBACE,IAAI,EAAE,GAAG;gBACT,IAAI,EAAE,WAAW;gBACjB,WAAW,EAAE,mCAAmC;aACjD;SACF;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"machineReadableHelp.js","sourceRoot":"","sources":["../../src/commands/machineReadableHelp.ts"],"names":[],"mappings":"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"}

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

@@ -1 +1 @@
-{"version":3,"file":"network.d.ts","sourceRoot":"","sources":["../../src/commands/network.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAkBzC;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAqC9D"}
+{"version":3,"file":"network.d.ts","sourceRoot":"","sources":["../../src/commands/network.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAyJzC;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAuI9D"}

package/dist/commands/network.js

@@ -1,8 +1,115 @@
+import * as fs from 'fs';
+import * as path from 'path';
 import { runCommand } from '../commands/shared/CommandRunner.js';
 import { jsonOption } from '../commands/shared/commonOptions.js';
-import { callCDP } from '../ipc/client.js';
+import { getHARData, callCDP, getNetworkHeaders } from '../ipc/client.js';
 import { validateIPCResponse } from '../ipc/index.js';
-import { formatCookies } from '../ui/formatters/index.js';
+import { getSessionFilePath } from '../session/paths.js';
+import { buildHAR } from '../telemetry/har/builder.js';
+import { isDaemonConnectionError } from '../ui/errors/utils.js';
+import { formatCookies, formatNetworkHeaders } from '../ui/formatters/index.js';
+import { sessionNotActiveError } from '../ui/messages/errors.js';
+import { AtomicFileWriter } from '../utils/atomicFile.js';
+import { EXIT_CODES } from '../utils/exitCodes.js';
+import { VERSION } from '../utils/version.js';
+/**
+ * Generate timestamped filename for HAR export in ~/.bdg/ directory.
+ *
+ * @returns Full path to HAR file in ~/.bdg/capture-YYYY-MM-DD-HHMMSS.har
+ *
+ * @example
+ * ```typescript
+ * generateHARFilename(); // "~/.bdg/capture-2025-11-19-143045.har"
+ * ```
+ */
+function generateHARFilename() {
+    const now = new Date();
+    const year = now.getFullYear();
+    const month = String(now.getMonth() + 1).padStart(2, '0');
+    const day = String(now.getDate()).padStart(2, '0');
+    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 sessionDir = path.dirname(getSessionFilePath('OUTPUT'));
+    return path.join(sessionDir, filename);
+}
+/**
+ * Fetch network requests from live daemon session.
+ *
+ * @returns Network requests array
+ * @throws Error if daemon connection fails or no network data available
+ */
+async function fetchFromLiveSession() {
+    const response = await getHARData();
+    validateIPCResponse(response);
+    if (!response.data?.requests) {
+        throw new Error('No network data in response');
+    }
+    return response.data.requests;
+}
+/**
+ * Fetch network requests from offline session.json file.
+ *
+ * @returns Network requests array
+ * @throws Error if session file not found or no network data available
+ */
+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
+ */
+function isDaemonUnavailable(error) {
+    if (isDaemonConnectionError(error)) {
+        return true;
+    }
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    return errorMessage.includes('No active session');
+}
+/**
+ * Get network requests from live session or session.json.
+ *
+ * Tries live daemon first, falls back to offline session file.
+ *
+ * @returns Network requests array
+ * @throws Error if no session available (live or offline)
+ */
+async function getNetworkRequests() {
+    try {
+        return await fetchFromLiveSession();
+    }
+    catch (error) {
+        if (isDaemonUnavailable(error)) {
+            return fetchFromOfflineSession();
+        }
+        throw error;
+    }
+}
+/**
+ * Format HAR export success message for human output.
+ *
+ * @param data - HAR export result data
+ * @returns Formatted success message
+ */
+function formatHARExport(data) {
+    return `✓ Exported ${data.entries} requests to ${data.file}`;
+}
 /**
  * Register network commands.
  *
@@ -10,7 +117,31 @@ import { formatCookies } from '../ui/formatters/index.js';
  */
 export function registerNetworkCommands(program) {
     const networkCmd = program.command('network').description('Inspect network state and resources');
-    // bdg network getCookies
+    networkCmd
+        .command('har [output-file]')
+        .description('Export network data as HAR 1.2 format')
+        .addOption(jsonOption)
+        .action(async (outputFile, options) => {
+        await runCommand(async () => {
+            const requests = await getNetworkRequests();
+            const outputPath = outputFile ?? generateHARFilename();
+            const dir = path.dirname(outputPath);
+            if (dir !== '.' && !fs.existsSync(dir)) {
+                fs.mkdirSync(dir, { recursive: true });
+            }
+            const har = buildHAR(requests, {
+                version: VERSION,
+            });
+            await AtomicFileWriter.writeAsync(outputPath, JSON.stringify(har, null, 2));
+            return {
+                success: true,
+                data: {
+                    file: outputPath,
+                    entries: har.log.entries.length,
+                },
+            };
+        }, options, formatHARExport);
+    });
     networkCmd
         .command('getCookies')
         .description('List cookies from the current page')
@@ -18,24 +149,68 @@ export function registerNetworkCommands(program) {
         .addOption(jsonOption)
         .action(async (options) => {
         await runCommand(async (opts) => {
-            // Build CDP method parameters
             const params = {};
             if (opts.url) {
                 params['urls'] = [opts.url];
             }
-            // Call CDP Network.getCookies
             const response = await callCDP('Network.getCookies', params);
-            // Validate IPC response (throws on error)
             validateIPCResponse(response);
-            // Extract cookies from CDP response
             const cookies = response.data?.result?.cookies ?? [];
             return {
                 success: true,
                 data: cookies,
             };
-        }, options, 
-        // Human-readable formatter
-        formatCookies);
+        }, options, formatCookies);
+    });
+    networkCmd
+        .command('headers [id]')
+        .description('Show HTTP headers (defaults to current main document)')
+        .option('--header <name>', 'Filter to specific header name')
+        .addOption(jsonOption)
+        .addHelpText('after', '\nNote: Without [id], shows headers for the current main document.\n      If the page has navigated, this will be the latest navigation, not the original URL.')
+        .action(async (id, options) => {
+        await runCommand(async (opts) => {
+            const response = await getNetworkHeaders({
+                ...(id && { id }),
+                ...(opts.header && { headerName: opts.header }),
+            });
+            validateIPCResponse(response);
+            if (!response.data) {
+                return {
+                    success: false,
+                    error: 'No data returned from worker',
+                    exitCode: EXIT_CODES.RESOURCE_NOT_FOUND,
+                };
+            }
+            return {
+                success: true,
+                data: response.data,
+            };
+        }, options, formatNetworkHeaders);
+    });
+    networkCmd
+        .command('document')
+        .description('Show main HTML document request details (alias for headers without ID)')
+        .option('--header <name>', 'Filter to specific header name')
+        .addOption(jsonOption)
+        .action(async (options) => {
+        await runCommand(async (opts) => {
+            const response = await getNetworkHeaders({
+                ...(opts.header && { headerName: opts.header }),
+            });
+            validateIPCResponse(response);
+            if (!response.data) {
+                return {
+                    success: false,
+                    error: 'No data returned from worker',
+                    exitCode: EXIT_CODES.RESOURCE_NOT_FOUND,
+                };
+            }
+            return {
+                success: true,
+                data: response.data,
+            };
+        }, options, formatNetworkHeaders);
     });
 }
 //# sourceMappingURL=network.js.map

package/dist/commands/network.js.map

@@ -1 +1 @@
-{"version":3,"file":"network.js","sourceRoot":"","sources":["../../src/commands/network.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,UAAU,EAAE,MAAM,oCAAoC,CAAC;AAChE,OAAO,EAAE,UAAU,EAAE,MAAM,oCAAoC,CAAC;AAChE,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAC1C,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAErD,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAUzD;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CAAC,OAAgB;IACtD,MAAM,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,WAAW,CAAC,qCAAqC,CAAC,CAAC;IAEjG,yBAAyB;IACzB,UAAU;SACP,OAAO,CAAC,YAAY,CAAC;SACrB,WAAW,CAAC,oCAAoC,CAAC;SACjD,MAAM,CAAC,aAAa,EAAE,uBAAuB,CAAC;SAC9C,SAAS,CAAC,UAAU,CAAC;SACrB,MAAM,CAAC,KAAK,EAAE,OAA0B,EAAE,EAAE;QAC3C,MAAM,UAAU,CACd,KAAK,EAAE,IAAI,EAAE,EAAE;YACb,8BAA8B;YAC9B,MAAM,MAAM,GAA4B,EAAE,CAAC;YAC3C,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;gBACb,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAC9B,CAAC;YAED,8BAA8B;YAC9B,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,oBAAoB,EAAE,MAAM,CAAC,CAAC;YAE7D,0CAA0C;YAC1C,mBAAmB,CAAC,QAAQ,CAAC,CAAC;YAE9B,oCAAoC;YACpC,MAAM,OAAO,GAAI,QAAQ,CAAC,IAAI,EAAE,MAAiC,EAAE,OAAO,IAAI,EAAE,CAAC;YAEjF,OAAO;gBACL,OAAO,EAAE,IAAI;gBACb,IAAI,EAAE,OAAO;aACd,CAAC;QACJ,CAAC,EACD,OAAO;QACP,2BAA2B;QAC3B,aAAa,CACd,CAAC;IACJ,CAAC,CAAC,CAAC;AACP,CAAC"}
+{"version":3,"file":"network.js","sourceRoot":"","sources":["../../src/commands/network.ts"],"names":[],"mappings":"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"}

package/dist/commands/peek.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"peek.d.ts","sourceRoot":"","sources":["../../src/commands/peek.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAsBzC;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA6G1D"}
+{"version":3,"file":"peek.d.ts","sourceRoot":"","sources":["../../src/commands/peek.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAwBzC;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAoH1D"}

package/dist/commands/peek.js

@@ -1,8 +1,9 @@
 import { jsonOption } from '../commands/shared/commonOptions.js';
 import { handleDaemonConnectionError } from '../commands/shared/daemonErrorHandler.js';
-import { positiveIntRule } from '../commands/shared/validation.js';
+import { positiveIntRule, resourceTypeRule } from '../commands/shared/validation.js';
 import { getPeek } from '../ipc/client.js';
 import { validateIPCResponse } from '../ipc/index.js';
+import { filterByResourceType } from '../telemetry/filters.js';
 import { formatPreview } from '../ui/formatters/preview.js';
 import { followingPreviewMessage, stoppedFollowingPreviewMessage } from '../ui/messages/preview.js';
 import { EXIT_CODES } from '../utils/exitCodes.js';
@@ -21,11 +22,13 @@ export function registerPeekCommand(program) {
         .option('-c, --console', 'Show only console messages', false)
         .option('-d, --dom', 'Show DOM/A11y tree data', false)
         .option('-f, --follow', 'Watch for updates (like tail -f)', false)
-        .option('--last <count>', 'Show last N items (network requests + console messages)', '10')
+        .option('--last <count>', 'Show last N items (0 = all, default: 10)', '10')
+        .option('--type <types>', 'Filter network requests by resource type (comma-separated: Document,XHR,Fetch,etc.)')
         .action(async (options) => {
-        // Validate --last option using validation layer
-        const lastRule = positiveIntRule({ min: 1, max: 1000, default: 10 });
+        const lastRule = positiveIntRule({ min: 1, max: 1000, default: 10, allowZeroForAll: true });
         const lastN = lastRule.validate(options.last);
+        const typeRule = resourceTypeRule();
+        const resourceTypes = typeRule.validate(options.type);
         const previewBase = {
             json: options.json,
             network: options.network,
@@ -37,15 +40,12 @@ export function registerPeekCommand(program) {
         };
         const showPreview = async () => {
             try {
-                // Fetch preview data via IPC from daemon
                 const response = await getPeek();
-                // Validate IPC response (will throw on error)
                 try {
                     validateIPCResponse(response);
                 }
                 catch {
                     const errorMsg = response.error ?? 'Unknown error';
-                    // No active session - use RESOURCE_NOT_FOUND
                     const exitCode = errorMsg.includes('No active session')
                         ? EXIT_CODES.RESOURCE_NOT_FOUND
                         : EXIT_CODES.SESSION_FILE_ERROR;
@@ -60,7 +60,6 @@ export function registerPeekCommand(program) {
                     }
                     return;
                 }
-                // Extract preview data from response
                 const output = response.data?.preview;
                 if (!output) {
                     const result = handleDaemonConnectionError('No preview data in response', {
@@ -74,15 +73,22 @@ export function registerPeekCommand(program) {
                     }
                     return;
                 }
-                // Clear screen before rendering to prevent stacked outputs in follow mode
                 if (options.follow) {
                     console.clear();
                 }
-                // Add current view timestamp for follow mode to show refresh time
                 const previewOptions = previewBase.follow
                     ? { ...previewBase, viewedAt: new Date() }
                     : previewBase;
-                console.log(formatPreview(output, previewOptions));
+                const filteredOutput = {
+                    ...output,
+                    data: {
+                        ...output.data,
+                        ...(output.data.network && {
+                            network: filterByResourceType(output.data.network, resourceTypes),
+                        }),
+                    },
+                };
+                console.log(formatPreview(filteredOutput, previewOptions));
             }
             catch {
                 const result = handleDaemonConnectionError('Daemon not running', {
@@ -96,13 +102,11 @@ export function registerPeekCommand(program) {
             }
         };
         if (options.follow) {
-            // Follow mode: update every second
             console.error(followingPreviewMessage());
             await showPreview();
             const followInterval = setInterval(() => {
                 void showPreview();
             }, 1000);
-            // Handle Ctrl+C gracefully
             process.on('SIGINT', () => {
                 clearInterval(followInterval);
                 console.error(stoppedFollowingPreviewMessage());
@@ -110,7 +114,6 @@ export function registerPeekCommand(program) {
             });
         }
         else {
-            // One-time preview
             await showPreview();
         }
     });

package/dist/commands/peek.js.map

@@ -1 +1 @@
-{"version":3,"file":"peek.js","sourceRoot":"","sources":["../../src/commands/peek.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"peek.js","sourceRoot":"","sources":["../../src/commands/peek.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAE,MAAM,oCAAoC,CAAC;AAChE,OAAO,EAAE,2BAA2B,EAAE,MAAM,yCAAyC,CAAC;AACtF,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACpF,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAC1C,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAE9D,OAAO,EAAE,aAAa,EAAuB,MAAM,4BAA4B,CAAC;AAChF,OAAO,EAAE,uBAAuB,EAAE,8BAA8B,EAAE,MAAM,0BAA0B,CAAC;AACnG,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAalD;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAAgB;IAClD,OAAO;SACJ,OAAO,CAAC,MAAM,CAAC;SACf,WAAW,CAAC,qDAAqD,CAAC;SAClE,SAAS,CAAC,UAAU,CAAC;SACrB,MAAM,CAAC,eAAe,EAAE,kDAAkD,EAAE,KAAK,CAAC;SAClF,MAAM,CAAC,eAAe,EAAE,4BAA4B,EAAE,KAAK,CAAC;SAC5D,MAAM,CAAC,eAAe,EAAE,4BAA4B,EAAE,KAAK,CAAC;SAC5D,MAAM,CAAC,WAAW,EAAE,yBAAyB,EAAE,KAAK,CAAC;SACrD,MAAM,CAAC,cAAc,EAAE,kCAAkC,EAAE,KAAK,CAAC;SACjE,MAAM,CAAC,gBAAgB,EAAE,0CAA0C,EAAE,IAAI,CAAC;SAC1E,MAAM,CACL,gBAAgB,EAChB,qFAAqF,CACtF;SACA,MAAM,CAAC,KAAK,EAAE,OAA2B,EAAE,EAAE;QAC5C,MAAM,QAAQ,GAAG,eAAe,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,eAAe,EAAE,IAAI,EAAE,CAAC,CAAC;QAC5F,MAAM,KAAK,GAAG,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAE9C,MAAM,QAAQ,GAAG,gBAAgB,EAAE,CAAC;QACpC,MAAM,aAAa,GAAG,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAEtD,MAAM,WAAW,GAAmB;YAClC,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,GAAG,EAAE,OAAO,CAAC,GAAG;YAChB,IAAI,EAAE,KAAK;YACX,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,MAAM,EAAE,OAAO,CAAC,MAAM;SACvB,CAAC;QAEF,MAAM,WAAW,GAAG,KAAK,IAAmB,EAAE;YAC5C,IAAI,CAAC;gBACH,MAAM,QAAQ,GAAG,MAAM,OAAO,EAAE,CAAC;gBAEjC,IAAI,CAAC;oBACH,mBAAmB,CAAC,QAAQ,CAAC,CAAC;gBAChC,CAAC;gBAAC,MAAM,CAAC;oBACP,MAAM,QAAQ,GAAG,QAAQ,CAAC,KAAK,IAAI,eAAe,CAAC;oBACnD,MAAM,QAAQ,GAAG,QAAQ,CAAC,QAAQ,CAAC,mBAAmB,CAAC;wBACrD,CAAC,CAAC,UAAU,CAAC,kBAAkB;wBAC/B,CAAC,CAAC,UAAU,CAAC,kBAAkB,CAAC;oBAClC,MAAM,MAAM,GAAG,2BAA2B,CAAC,QAAQ,EAAE;wBACnD,IAAI,EAAE,OAAO,CAAC,IAAI;wBAClB,MAAM,EAAE,OAAO,CAAC,MAAM;wBACtB,eAAe,EAAE,IAAI;wBACrB,QAAQ;qBACT,CAAC,CAAC;oBACH,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;wBACtB,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;oBAChC,CAAC;oBACD,OAAO;gBACT,CAAC;gBAED,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,EAAE,OAAgC,CAAC;gBAC/D,IAAI,CAAC,MAAM,EAAE,CAAC;oBACZ,MAAM,MAAM,GAAG,2BAA2B,CAAC,6BAA6B,EAAE;wBACxE,IAAI,EAAE,OAAO,CAAC,IAAI;wBAClB,MAAM,EAAE,OAAO,CAAC,MAAM;wBACtB,eAAe,EAAE,IAAI;wBACrB,QAAQ,EAAE,UAAU,CAAC,kBAAkB;qBACxC,CAAC,CAAC;oBACH,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;wBACtB,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;oBAChC,CAAC;oBACD,OAAO;gBACT,CAAC;gBAED,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;oBACnB,OAAO,CAAC,KAAK,EAAE,CAAC;gBAClB,CAAC;gBAED,MAAM,cAAc,GAAmB,WAAW,CAAC,MAAM;oBACvD,CAAC,CAAC,EAAE,GAAG,WAAW,EAAE,QAAQ,EAAE,IAAI,IAAI,EAAE,EAAE;oBAC1C,CAAC,CAAC,WAAW,CAAC;gBAEhB,MAAM,cAAc,GAAc;oBAChC,GAAG,MAAM;oBACT,IAAI,EAAE;wBACJ,GAAG,MAAM,CAAC,IAAI;wBACd,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,IAAI;4BACzB,OAAO,EAAE,oBAAoB,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,aAAa,CAAC;yBAClE,CAAC;qBACH;iBACF,CAAC;gBAEF,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,cAAc,EAAE,cAAc,CAAC,CAAC,CAAC;YAC7D,CAAC;YAAC,MAAM,CAAC;gBACP,MAAM,MAAM,GAAG,2BAA2B,CAAC,oBAAoB,EAAE;oBAC/D,IAAI,EAAE,OAAO,CAAC,IAAI;oBAClB,MAAM,EAAE,OAAO,CAAC,MAAM;oBACtB,eAAe,EAAE,IAAI;iBACtB,CAAC,CAAC;gBACH,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;oBACtB,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;gBAChC,CAAC;YACH,CAAC;QACH,CAAC,CAAC;QAEF,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;YACnB,OAAO,CAAC,KAAK,CAAC,uBAAuB,EAAE,CAAC,CAAC;YACzC,MAAM,WAAW,EAAE,CAAC;YACpB,MAAM,cAAc,GAAG,WAAW,CAAC,GAAG,EAAE;gBACtC,KAAK,WAAW,EAAE,CAAC;YACrB,CAAC,EAAE,IAAI,CAAC,CAAC;YAET,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE;gBACxB,aAAa,CAAC,cAAc,CAAC,CAAC;gBAC9B,OAAO,CAAC,KAAK,CAAC,8BAA8B,EAAE,CAAC,CAAC;gBAChD,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;YACnC,CAAC,CAAC,CAAC;QACL,CAAC;aAAM,CAAC;YACN,MAAM,WAAW,EAAE,CAAC;QACtB,CAAC;IACH,CAAC,CAAC,CAAC;AACP,CAAC"}

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

@@ -21,6 +21,8 @@ export interface CommandResult<T = unknown> {
     exitCode?: number;
     /** Optional error context (suggestions, examples, etc.) */
     errorContext?: Record<string, unknown>;
+    /** Optional hint message to display on stderr (for successful commands with guidance) */
+    hint?: string;
 }
 /**
  * Handler function type.

package/dist/commands/shared/CommandRunner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CommandRunner.d.ts","sourceRoot":"","sources":["../../../src/commands/shared/CommandRunner.ts"],"names":[],"mappings":"AAMA;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,sDAAsD;IACtD,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC,GAAG,OAAO;IACxC,oCAAoC;IACpC,OAAO,EAAE,OAAO,CAAC;IACjB,+CAA+C;IAC/C,IAAI,CAAC,EAAE,CAAC,CAAC;IACT,0CAA0C;IAC1C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qFAAqF;IACrF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2DAA2D;IAC3D,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACxC;AAED;;;GAGG;AACH,MAAM,MAAM,cAAc,CAAC,QAAQ,SAAS,kBAAkB,EAAE,OAAO,GAAG,OAAO,IAAI,CACnF,OAAO,EAAE,QAAQ,KACd,OAAO,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC;AAErC;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,CAAC,OAAO,GAAG,OAAO,IAAI,CAAC,IAAI,EAAE,OAAO,KAAK,MAAM,CAAC;AAE5E;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,UAAU,CAAC,QAAQ,SAAS,kBAAkB,EAAE,OAAO,GAAG,OAAO,EACrF,OAAO,EAAE,cAAc,CAAC,QAAQ,EAAE,OAAO,CAAC,EAC1C,OAAO,EAAE,QAAQ,EACjB,SAAS,CAAC,EAAE,gBAAgB,CAAC,OAAO,CAAC,GACpC,OAAO,CAAC,IAAI,CAAC,CAyFf"}
+{"version":3,"file":"CommandRunner.d.ts","sourceRoot":"","sources":["../../../src/commands/shared/CommandRunner.ts"],"names":[],"mappings":"AAMA;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,sDAAsD;IACtD,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC,GAAG,OAAO;IACxC,oCAAoC;IACpC,OAAO,EAAE,OAAO,CAAC;IACjB,+CAA+C;IAC/C,IAAI,CAAC,EAAE,CAAC,CAAC;IACT,0CAA0C;IAC1C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qFAAqF;IACrF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2DAA2D;IAC3D,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,yFAAyF;IACzF,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,MAAM,MAAM,cAAc,CAAC,QAAQ,SAAS,kBAAkB,EAAE,OAAO,GAAG,OAAO,IAAI,CACnF,OAAO,EAAE,QAAQ,KACd,OAAO,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC;AAErC;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,CAAC,OAAO,GAAG,OAAO,IAAI,CAAC,IAAI,EAAE,OAAO,KAAK,MAAM,CAAC;AAE5E;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,UAAU,CAAC,QAAQ,SAAS,kBAAkB,EAAE,OAAO,GAAG,OAAO,EACrF,OAAO,EAAE,cAAc,CAAC,QAAQ,EAAE,OAAO,CAAC,EAC1C,OAAO,EAAE,QAAQ,EACjB,SAAS,CAAC,EAAE,gBAAgB,CAAC,OAAO,CAAC,GACpC,OAAO,CAAC,IAAI,CAAC,CAqFf"}

package/dist/commands/shared/CommandRunner.js

@@ -33,7 +33,6 @@ export async function runCommand(handler, options, formatter) {
     try {
         const result = await handler(options);
         if (!result.success) {
-            // Error result from handler
             if (options.json) {
                 const errorData = {
                     ...(result.exitCode !== undefined && { exitCode: result.exitCode }),
@@ -43,7 +42,6 @@ export async function runCommand(handler, options, formatter) {
             }
             else {
                 console.error(result.error ? genericError(result.error) : unknownError());
-                // Show errorContext suggestions in human-readable mode
                 if (result.errorContext && typeof result.errorContext === 'object') {
                     for (const value of Object.values(result.errorContext)) {
                         if (typeof value === 'string') {
@@ -54,7 +52,9 @@ export async function runCommand(handler, options, formatter) {
             }
             process.exit(result.exitCode ?? EXIT_CODES.UNHANDLED_EXCEPTION);
         }
-        // Success - output data
+        if (result.hint) {
+            console.error(result.hint);
+        }
         if (options.json) {
             console.log(JSON.stringify(result.data, null, 2));
         }
@@ -63,20 +63,17 @@ export async function runCommand(handler, options, formatter) {
             console.log(formattedOutput);
         }
         else {
-            // Fallback: JSON output if no formatter provided
             console.log(JSON.stringify(result.data, null, 2));
         }
         process.exit(EXIT_CODES.SUCCESS);
     }
     catch (error) {
-        // Handle CommandError with metadata and custom exit code
         if (error instanceof CommandError) {
             if (options.json) {
                 console.log(JSON.stringify(OutputBuilder.buildJsonError(error.message, error.metadata), null, 2));
             }
             else {
                 console.error(genericError(error.message));
-                // Output metadata as additional help text
                 for (const value of Object.values(error.metadata)) {
                     console.error(value);
                 }
@@ -84,7 +81,6 @@ export async function runCommand(handler, options, formatter) {
             process.exit(error.exitCode);
         }
         const errorMessage = getErrorMessage(error);
-        // Detect daemon connection errors
         if (isDaemonConnectionError(error)) {
             if (options.json) {
                 console.log(JSON.stringify(OutputBuilder.buildJsonError('Daemon not running', {
@@ -96,7 +92,6 @@ export async function runCommand(handler, options, formatter) {
             }
             process.exit(EXIT_CODES.RESOURCE_NOT_FOUND);
         }
-        // Generic error
         if (options.json) {
             console.log(JSON.stringify(OutputBuilder.buildJsonError(errorMessage), null, 2));
         }