browser-debugger-cli 0.6.6 → 0.6.8

package/dist/utils/errorMapping.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Centralized IPC error-to-exit code mapping.
+ *
+ * Provides a single source of truth for mapping IPC error codes and connection
+ * errors to semantic exit codes. This eliminates scattered, inconsistent error
+ * handling across commands.
+ *
+ * WHY: Different commands had duplicate, inconsistent error-to-exit-code logic.
+ * Some used helper functions, others used string matching. This module provides
+ * consistent, maintainable error handling.
+ */
+import { IPCErrorCode } from '../ipc/index.js';
+/**
+ * Map IPC error codes to semantic exit codes.
+ *
+ * @param errorCode - IPC error code from daemon response
+ * @returns Semantic exit code for the error
+ *
+ * @example
+ * ```typescript
+ * const exitCode = getExitCodeForIPCError(response.errorCode);
+ * process.exit(exitCode);
+ * ```
+ */
+export declare function getExitCodeForIPCError(errorCode?: IPCErrorCode): number;
+/**
+ * Map connection error messages to semantic exit codes.
+ *
+ * Handles common socket and connection errors that indicate the daemon
+ * is not running or unreachable.
+ *
+ * @param errorMessage - Error message string to analyze
+ * @returns Semantic exit code for the error
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await connectToDaemon();
+ * } catch (error) {
+ *   const exitCode = getExitCodeForConnectionError(getErrorMessage(error));
+ *   process.exit(exitCode);
+ * }
+ * ```
+ */
+export declare function getExitCodeForConnectionError(errorMessage: string): number;
+/**
+ * Check if an error message indicates the daemon is not running.
+ *
+ * @param errorMessage - Error message to check
+ * @returns True if the error indicates daemon is not running
+ *
+ * @example
+ * ```typescript
+ * if (isDaemonNotRunningError(errorMessage)) {
+ *   console.error('Start a session first with: bdg <url>');
+ * }
+ * ```
+ */
+export declare function isDaemonNotRunningError(errorMessage: string): boolean;
+//# sourceMappingURL=errorMapping.d.ts.map

package/dist/utils/errorMapping.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errorMapping.d.ts","sourceRoot":"","sources":["../../src/utils/errorMapping.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAG9C;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,CAAC,EAAE,YAAY,GAAG,MAAM,CAoBvE;AASD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,6BAA6B,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAgB1E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAErE"}

package/dist/utils/errorMapping.js

@@ -0,0 +1,97 @@
+/**
+ * Centralized IPC error-to-exit code mapping.
+ *
+ * Provides a single source of truth for mapping IPC error codes and connection
+ * errors to semantic exit codes. This eliminates scattered, inconsistent error
+ * handling across commands.
+ *
+ * WHY: Different commands had duplicate, inconsistent error-to-exit-code logic.
+ * Some used helper functions, others used string matching. This module provides
+ * consistent, maintainable error handling.
+ */
+import { IPCErrorCode } from '../ipc/index.js';
+import { EXIT_CODES } from '../utils/exitCodes.js';
+/**
+ * Map IPC error codes to semantic exit codes.
+ *
+ * @param errorCode - IPC error code from daemon response
+ * @returns Semantic exit code for the error
+ *
+ * @example
+ * ```typescript
+ * const exitCode = getExitCodeForIPCError(response.errorCode);
+ * process.exit(exitCode);
+ * ```
+ */
+export function getExitCodeForIPCError(errorCode) {
+    switch (errorCode) {
+        case IPCErrorCode.NO_SESSION:
+            return EXIT_CODES.RESOURCE_NOT_FOUND;
+        case IPCErrorCode.SESSION_ALREADY_RUNNING:
+            return EXIT_CODES.RESOURCE_ALREADY_EXISTS;
+        case IPCErrorCode.CHROME_LAUNCH_FAILED:
+            return EXIT_CODES.CHROME_LAUNCH_FAILURE;
+        case IPCErrorCode.CDP_TIMEOUT:
+            return EXIT_CODES.CDP_TIMEOUT;
+        case IPCErrorCode.SESSION_KILL_FAILED:
+        case IPCErrorCode.WORKER_START_FAILED:
+        case IPCErrorCode.DAEMON_ERROR:
+        case undefined:
+            return EXIT_CODES.UNHANDLED_EXCEPTION;
+    }
+}
+/**
+ * Check if error indicates socket connection failure (daemon not running).
+ */
+function isSocketConnectionError(lowerMessage) {
+    return lowerMessage.includes('enoent') || lowerMessage.includes('econnrefused');
+}
+/**
+ * Map connection error messages to semantic exit codes.
+ *
+ * Handles common socket and connection errors that indicate the daemon
+ * is not running or unreachable.
+ *
+ * @param errorMessage - Error message string to analyze
+ * @returns Semantic exit code for the error
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await connectToDaemon();
+ * } catch (error) {
+ *   const exitCode = getExitCodeForConnectionError(getErrorMessage(error));
+ *   process.exit(exitCode);
+ * }
+ * ```
+ */
+export function getExitCodeForConnectionError(errorMessage) {
+    const lowerMessage = errorMessage.toLowerCase();
+    if (isSocketConnectionError(lowerMessage)) {
+        return EXIT_CODES.RESOURCE_NOT_FOUND;
+    }
+    if (lowerMessage.includes('no active session')) {
+        return EXIT_CODES.RESOURCE_NOT_FOUND;
+    }
+    if (lowerMessage.includes('timeout')) {
+        return EXIT_CODES.CDP_TIMEOUT;
+    }
+    return EXIT_CODES.SESSION_FILE_ERROR;
+}
+/**
+ * Check if an error message indicates the daemon is not running.
+ *
+ * @param errorMessage - Error message to check
+ * @returns True if the error indicates daemon is not running
+ *
+ * @example
+ * ```typescript
+ * if (isDaemonNotRunningError(errorMessage)) {
+ *   console.error('Start a session first with: bdg <url>');
+ * }
+ * ```
+ */
+export function isDaemonNotRunningError(errorMessage) {
+    return isSocketConnectionError(errorMessage.toLowerCase());
+}
+//# sourceMappingURL=errorMapping.js.map

package/dist/utils/errorMapping.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errorMapping.js","sourceRoot":"","sources":["../../src/utils/errorMapping.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAElD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,sBAAsB,CAAC,SAAwB;IAC7D,QAAQ,SAAS,EAAE,CAAC;QAClB,KAAK,YAAY,CAAC,UAAU;YAC1B,OAAO,UAAU,CAAC,kBAAkB,CAAC;QAEvC,KAAK,YAAY,CAAC,uBAAuB;YACvC,OAAO,UAAU,CAAC,uBAAuB,CAAC;QAE5C,KAAK,YAAY,CAAC,oBAAoB;YACpC,OAAO,UAAU,CAAC,qBAAqB,CAAC;QAE1C,KAAK,YAAY,CAAC,WAAW;YAC3B,OAAO,UAAU,CAAC,WAAW,CAAC;QAEhC,KAAK,YAAY,CAAC,mBAAmB,CAAC;QACtC,KAAK,YAAY,CAAC,mBAAmB,CAAC;QACtC,KAAK,YAAY,CAAC,YAAY,CAAC;QAC/B,KAAK,SAAS;YACZ,OAAO,UAAU,CAAC,mBAAmB,CAAC;IAC1C,CAAC;AACH,CAAC;AAED;;GAEG;AACH,SAAS,uBAAuB,CAAC,YAAoB;IACnD,OAAO,YAAY,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,YAAY,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC;AAClF,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,6BAA6B,CAAC,YAAoB;IAChE,MAAM,YAAY,GAAG,YAAY,CAAC,WAAW,EAAE,CAAC;IAEhD,IAAI,uBAAuB,CAAC,YAAY,CAAC,EAAE,CAAC;QAC1C,OAAO,UAAU,CAAC,kBAAkB,CAAC;IACvC,CAAC;IAED,IAAI,YAAY,CAAC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,CAAC;QAC/C,OAAO,UAAU,CAAC,kBAAkB,CAAC;IACvC,CAAC;IAED,IAAI,YAAY,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;QACrC,OAAO,UAAU,CAAC,WAAW,CAAC;IAChC,CAAC;IAED,OAAO,UAAU,CAAC,kBAAkB,CAAC;AACvC,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,uBAAuB,CAAC,YAAoB;IAC1D,OAAO,uBAAuB,CAAC,YAAY,CAAC,WAAW,EAAE,CAAC,CAAC;AAC7D,CAAC"}

package/dist/utils/file.d.ts

@@ -0,0 +1,27 @@
+/**
+ * File system utilities for safe file operations.
+ *
+ * Provides wrapper functions that handle errors gracefully and log failures
+ * at debug level instead of throwing exceptions.
+ */
+import type { Logger } from '../ui/logging/index.js';
+/**
+ * Safely remove a file, logging any errors at debug level.
+ *
+ * Uses `fs.rmSync` with `force: true` to avoid errors if the file doesn't exist.
+ * Any errors during removal are logged at debug level instead of thrown.
+ *
+ * @param path - Absolute path to the file to remove
+ * @param context - Human-readable description for debug logging (e.g., "metadata file")
+ * @param log - Logger instance to use for debug output
+ * @returns True if file was removed or didn't exist, false if removal failed
+ *
+ * @example
+ * ```typescript
+ * const log = createLogger('cleanup');
+ * safeRemoveFile('/path/to/session.pid', 'session PID file', log);
+ * // On error logs: [cleanup] Failed to remove session PID file: EACCES: permission denied
+ * ```
+ */
+export declare function safeRemoveFile(path: string, context: string, log: Logger): boolean;
+//# sourceMappingURL=file.d.ts.map

package/dist/utils/file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file.d.ts","sourceRoot":"","sources":["../../src/utils/file.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAGpD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAQlF"}

package/dist/utils/file.js

@@ -0,0 +1,37 @@
+/**
+ * File system utilities for safe file operations.
+ *
+ * Provides wrapper functions that handle errors gracefully and log failures
+ * at debug level instead of throwing exceptions.
+ */
+import * as fs from 'fs';
+import { logDebugError } from '../ui/logging/index.js';
+/**
+ * Safely remove a file, logging any errors at debug level.
+ *
+ * Uses `fs.rmSync` with `force: true` to avoid errors if the file doesn't exist.
+ * Any errors during removal are logged at debug level instead of thrown.
+ *
+ * @param path - Absolute path to the file to remove
+ * @param context - Human-readable description for debug logging (e.g., "metadata file")
+ * @param log - Logger instance to use for debug output
+ * @returns True if file was removed or didn't exist, false if removal failed
+ *
+ * @example
+ * ```typescript
+ * const log = createLogger('cleanup');
+ * safeRemoveFile('/path/to/session.pid', 'session PID file', log);
+ * // On error logs: [cleanup] Failed to remove session PID file: EACCES: permission denied
+ * ```
+ */
+export function safeRemoveFile(path, context, log) {
+    try {
+        fs.rmSync(path, { force: true });
+        return true;
+    }
+    catch (error) {
+        logDebugError(log, `remove ${context}`, error);
+        return false;
+    }
+}
+//# sourceMappingURL=file.js.map

package/dist/utils/file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file.js","sourceRoot":"","sources":["../../src/utils/file.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AAGzB,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAEtD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,OAAe,EAAE,GAAW;IACvE,IAAI,CAAC;QACH,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACjC,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,aAAa,CAAC,GAAG,EAAE,UAAU,OAAO,EAAE,EAAE,KAAK,CAAC,CAAC;QAC/C,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/utils/levenshtein.d.ts

@@ -25,21 +25,4 @@
  * ```
  */
 export declare function levenshteinDistance(str1: string, str2: string): number;
-/**
- * Find closest matches from a list of candidates based on edit distance.
- *
- * @param target - The string to match against
- * @param candidates - Array of candidate strings
- * @param maxResults - Maximum number of results to return (default: 3)
- * @param maxDistance - Maximum edit distance to consider (default: half target length or 3)
- * @returns Array of closest matching candidates, sorted by distance
- *
- * @example
- * ```typescript
- * const candidates = ['apple', 'application', 'apply', 'banana'];
- * findClosestMatches('aple', candidates); // ['apple', 'apply']
- * findClosestMatches('app', candidates, 2); // ['apple', 'apply']
- * ```
- */
-export declare function findClosestMatches(target: string, candidates: string[], maxResults?: number, maxDistance?: number): string[];
 //# sourceMappingURL=levenshtein.d.ts.map

package/dist/utils/levenshtein.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"levenshtein.d.ts","sourceRoot":"","sources":["../../src/utils/levenshtein.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CA6BtE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAAE,EACpB,UAAU,GAAE,MAAU,EACtB,WAAW,CAAC,EAAE,MAAM,GACnB,MAAM,EAAE,CAkBV"}
+{"version":3,"file":"levenshtein.d.ts","sourceRoot":"","sources":["../../src/utils/levenshtein.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CA6BtE"}

package/dist/utils/levenshtein.js

@@ -51,35 +51,4 @@ export function levenshteinDistance(str1, str2) {
     }
     return matrix[len1]?.[len2] ?? 0;
 }
-/**
- * Find closest matches from a list of candidates based on edit distance.
- *
- * @param target - The string to match against
- * @param candidates - Array of candidate strings
- * @param maxResults - Maximum number of results to return (default: 3)
- * @param maxDistance - Maximum edit distance to consider (default: half target length or 3)
- * @returns Array of closest matching candidates, sorted by distance
- *
- * @example
- * ```typescript
- * const candidates = ['apple', 'application', 'apply', 'banana'];
- * findClosestMatches('aple', candidates); // ['apple', 'apply']
- * findClosestMatches('app', candidates, 2); // ['apple', 'apply']
- * ```
- */
-export function findClosestMatches(target, candidates, maxResults = 3, maxDistance) {
-    const targetLower = target.toLowerCase();
-    const threshold = maxDistance ?? Math.max(targetLower.length / 2, 3);
-    const matches = [];
-    for (const candidate of candidates) {
-        const distance = levenshteinDistance(targetLower, candidate.toLowerCase());
-        if (distance <= threshold) {
-            matches.push({ candidate, distance });
-        }
-    }
-    return matches
-        .sort((a, b) => a.distance - b.distance)
-        .slice(0, maxResults)
-        .map((m) => m.candidate);
-}
 //# sourceMappingURL=levenshtein.js.map

package/dist/utils/levenshtein.js.map

@@ -1 +1 @@
-{"version":3,"file":"levenshtein.js","sourceRoot":"","sources":["../../src/utils/levenshtein.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"levenshtein.js","sourceRoot":"","sources":["../../src/utils/levenshtein.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAY,EAAE,IAAY;IAC5D,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC;IACzB,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC;IACzB,MAAM,MAAM,GAAe,EAAE,CAAC;IAE9B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC;QAC/B,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IACD,MAAM,QAAQ,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;IAC3B,IAAI,QAAQ,EAAE,CAAC;QACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC;YAC/B,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;IAED,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC;QAC/B,MAAM,UAAU,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;QAC7B,IAAI,CAAC,UAAU;YAAE,SAAS;QAE1B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC;YAC/B,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YACjD,MAAM,QAAQ,GAAG,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;YAC/C,MAAM,SAAS,GAAG,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;YAC/C,MAAM,YAAY,GAAG,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC;YAC1D,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,SAAS,EAAE,YAAY,CAAC,CAAC;QAC9D,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACnC,CAAC"}

package/dist/utils/strings.d.ts

@@ -0,0 +1,14 @@
+/**
+ * String manipulation utilities.
+ */
+/**
+ * Truncate text to a maximum character length.
+ *
+ * Adds an ellipsis character when text is truncated.
+ *
+ * @param text - Text to truncate
+ * @param maxLength - Maximum character length (default: 500)
+ * @returns Truncated text with ellipsis if needed
+ */
+export declare function truncateByLength(text: string, maxLength?: number): string;
+//# sourceMappingURL=strings.d.ts.map

package/dist/utils/strings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"strings.d.ts","sourceRoot":"","sources":["../../src/utils/strings.ts"],"names":[],"mappings":"AAAA;;GAEG;AAOH;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,GAAE,MAA2B,GAAG,MAAM,CAK7F"}

package/dist/utils/strings.js

@@ -0,0 +1,23 @@
+/**
+ * String manipulation utilities.
+ */
+/**
+ * Default maximum text length for truncation.
+ */
+const DEFAULT_MAX_LENGTH = 500;
+/**
+ * Truncate text to a maximum character length.
+ *
+ * Adds an ellipsis character when text is truncated.
+ *
+ * @param text - Text to truncate
+ * @param maxLength - Maximum character length (default: 500)
+ * @returns Truncated text with ellipsis if needed
+ */
+export function truncateByLength(text, maxLength = DEFAULT_MAX_LENGTH) {
+    if (text.length <= maxLength) {
+        return text;
+    }
+    return text.slice(0, maxLength - 1) + '…';
+}
+//# sourceMappingURL=strings.js.map

package/dist/utils/strings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"strings.js","sourceRoot":"","sources":["../../src/utils/strings.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,MAAM,kBAAkB,GAAG,GAAG,CAAC;AAE/B;;;;;;;;GAQG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY,EAAE,YAAoB,kBAAkB;IACnF,IAAI,IAAI,CAAC,MAAM,IAAI,SAAS,EAAE,CAAC;QAC7B,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC;AAC5C,CAAC"}

package/dist/utils/taskMappings.d.ts

@@ -21,27 +21,10 @@ export interface TaskMapping {
  * Maps common automation intents to optimal command patterns.
  */
 export declare const TASK_MAPPINGS: Record<string, TaskMapping>;
-/**
- * Get task mapping by key.
- *
- * @param taskKey - Task identifier
- * @returns Task mapping if found, undefined otherwise
- */
-export declare function getTaskMapping(taskKey: string): TaskMapping | undefined;
 /**
  * Get all task mappings.
  *
  * @returns Complete task mapping registry
  */
 export declare function getAllTaskMappings(): Record<string, TaskMapping>;
-/**
- * Search task mappings by description keyword.
- *
- * @param keyword - Search term (case-insensitive)
- * @returns Matching task mappings with keys
- */
-export declare function searchTaskMappings(keyword: string): Array<{
-    key: string;
-    mapping: TaskMapping;
-}>;
 //# sourceMappingURL=taskMappings.d.ts.map

package/dist/utils/taskMappings.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"taskMappings.d.ts","sourceRoot":"","sources":["../../src/utils/taskMappings.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,oDAAoD;IACpD,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,sCAAsC;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,gCAAgC;IAChC,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;;GAIG;AACH,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAgGrD,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAEvE;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAEhE;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,WAAW,CAAA;CAAE,CAAC,CAKhG"}
+{"version":3,"file":"taskMappings.d.ts","sourceRoot":"","sources":["../../src/utils/taskMappings.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,oDAAoD;IACpD,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,sCAAsC;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,gCAAgC;IAChC,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;;GAIG;AACH,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAkHrD,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAEhE"}

package/dist/utils/taskMappings.js

@@ -65,9 +65,24 @@ export const TASK_MAPPINGS = {
         description: 'Get HTTP headers for specific request',
         cdpAlternative: 'Network.getResponseBody + event data',
     },
-    query_console_logs: {
-        commands: ['console query'],
-        description: 'Query and filter console log messages',
+    inspect_console: {
+        commands: ['console'],
+        description: 'Smart console inspection (current page, errors/warnings deduplicated)',
+        cdpAlternative: 'Runtime.consoleAPICalled events',
+    },
+    console_history: {
+        commands: ['console --history'],
+        description: 'Show console messages from all page loads',
+        cdpAlternative: 'Runtime.consoleAPICalled events',
+    },
+    stream_console: {
+        commands: ['console --follow'],
+        description: 'Stream console messages in real-time',
+        cdpAlternative: 'Runtime.consoleAPICalled event subscription',
+    },
+    list_console_messages: {
+        commands: ['console --list'],
+        description: 'List all console messages chronologically',
         cdpAlternative: 'Runtime.consoleAPICalled events',
     },
     preview_data: {
@@ -91,15 +106,6 @@ export const TASK_MAPPINGS = {
         cdpAlternative: 'IPC ping + process checks',
     },
 };
-/**
- * Get task mapping by key.
- *
- * @param taskKey - Task identifier
- * @returns Task mapping if found, undefined otherwise
- */
-export function getTaskMapping(taskKey) {
-    return TASK_MAPPINGS[taskKey];
-}
 /**
  * Get all task mappings.
  *
@@ -108,16 +114,4 @@ export function getTaskMapping(taskKey) {
 export function getAllTaskMappings() {
     return TASK_MAPPINGS;
 }
-/**
- * Search task mappings by description keyword.
- *
- * @param keyword - Search term (case-insensitive)
- * @returns Matching task mappings with keys
- */
-export function searchTaskMappings(keyword) {
-    const lowerKeyword = keyword.toLowerCase();
-    return Object.entries(TASK_MAPPINGS)
-        .filter(([, mapping]) => mapping.description.toLowerCase().includes(lowerKeyword))
-        .map(([key, mapping]) => ({ key, mapping }));
-}
 //# sourceMappingURL=taskMappings.js.map

package/dist/utils/taskMappings.js.map

@@ -1 +1 @@
-{"version":3,"file":"taskMappings.js","sourceRoot":"","sources":["../../src/utils/taskMappings.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"taskMappings.js","sourceRoot":"","sources":["../../src/utils/taskMappings.ts"],"names":[],"mappings":"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"}

package/dist/utils/typeGuards.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Type guards for runtime type validation.
+ *
+ * Provides type-safe validation of IPC response data, replacing unsafe
+ * `as unknown as` type assertions with proper runtime checks.
+ *
+ * WHY: Type assertions bypass TypeScript's type system and can lead to
+ * runtime errors. Type guards provide actual runtime validation while
+ * maintaining type safety.
+ */
+import type { NetworkRequest, ConsoleMessage } from '../types.js';
+/**
+ * Type guard to check if a value is a valid NetworkRequest.
+ *
+ * Validates the presence of required NetworkRequest properties.
+ *
+ * @param value - Unknown value to validate
+ * @returns True if value is a valid NetworkRequest
+ *
+ * @example
+ * ```typescript
+ * if (isNetworkRequest(item)) {
+ *   console.log(item.url); // TypeScript knows item is NetworkRequest
+ * }
+ * ```
+ */
+export declare function isNetworkRequest(value: unknown): value is NetworkRequest;
+/**
+ * Type guard to check if a value is a valid ConsoleMessage.
+ *
+ * Validates the presence of required ConsoleMessage properties.
+ *
+ * @param value - Unknown value to validate
+ * @returns True if value is a valid ConsoleMessage
+ *
+ * @example
+ * ```typescript
+ * if (isConsoleMessage(item)) {
+ *   console.log(item.text); // TypeScript knows item is ConsoleMessage
+ * }
+ * ```
+ */
+export declare function isConsoleMessage(value: unknown): value is ConsoleMessage;
+/**
+ * Validate and return a details item with proper type safety.
+ *
+ * Replaces unsafe `as unknown as` assertions with runtime validation.
+ * Throws CommandError if validation fails.
+ *
+ * @param item - Unknown item from IPC response
+ * @param type - Expected type ('network' or 'console')
+ * @returns Validated NetworkRequest or ConsoleMessage
+ * @throws CommandError if item fails validation
+ *
+ * @example
+ * ```typescript
+ * const validatedItem = validateDetailsItem(response.data.item, 'network');
+ * // validatedItem is now typed as NetworkRequest | ConsoleMessage
+ * ```
+ */
+export declare function validateDetailsItem(item: unknown, type: 'network' | 'console'): NetworkRequest | ConsoleMessage;
+//# sourceMappingURL=typeGuards.d.ts.map

package/dist/utils/typeGuards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typeGuards.d.ts","sourceRoot":"","sources":["../../src/utils/typeGuards.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAIjE;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAaxE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAYxE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,OAAO,EACb,IAAI,EAAE,SAAS,GAAG,SAAS,GAC1B,cAAc,GAAG,cAAc,CA4BjC"}

package/dist/utils/typeGuards.js

@@ -0,0 +1,94 @@
+/**
+ * Type guards for runtime type validation.
+ *
+ * Provides type-safe validation of IPC response data, replacing unsafe
+ * `as unknown as` type assertions with proper runtime checks.
+ *
+ * WHY: Type assertions bypass TypeScript's type system and can lead to
+ * runtime errors. Type guards provide actual runtime validation while
+ * maintaining type safety.
+ */
+import { CommandError } from '../ui/errors/index.js';
+import { EXIT_CODES } from '../utils/exitCodes.js';
+/**
+ * Type guard to check if a value is a valid NetworkRequest.
+ *
+ * Validates the presence of required NetworkRequest properties.
+ *
+ * @param value - Unknown value to validate
+ * @returns True if value is a valid NetworkRequest
+ *
+ * @example
+ * ```typescript
+ * if (isNetworkRequest(item)) {
+ *   console.log(item.url); // TypeScript knows item is NetworkRequest
+ * }
+ * ```
+ */
+export function isNetworkRequest(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const record = value;
+    return (typeof record['requestId'] === 'string' &&
+        typeof record['url'] === 'string' &&
+        typeof record['method'] === 'string' &&
+        typeof record['timestamp'] === 'number');
+}
+/**
+ * Type guard to check if a value is a valid ConsoleMessage.
+ *
+ * Validates the presence of required ConsoleMessage properties.
+ *
+ * @param value - Unknown value to validate
+ * @returns True if value is a valid ConsoleMessage
+ *
+ * @example
+ * ```typescript
+ * if (isConsoleMessage(item)) {
+ *   console.log(item.text); // TypeScript knows item is ConsoleMessage
+ * }
+ * ```
+ */
+export function isConsoleMessage(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const record = value;
+    return (typeof record['type'] === 'string' &&
+        typeof record['text'] === 'string' &&
+        typeof record['timestamp'] === 'number');
+}
+/**
+ * Validate and return a details item with proper type safety.
+ *
+ * Replaces unsafe `as unknown as` assertions with runtime validation.
+ * Throws CommandError if validation fails.
+ *
+ * @param item - Unknown item from IPC response
+ * @param type - Expected type ('network' or 'console')
+ * @returns Validated NetworkRequest or ConsoleMessage
+ * @throws CommandError if item fails validation
+ *
+ * @example
+ * ```typescript
+ * const validatedItem = validateDetailsItem(response.data.item, 'network');
+ * // validatedItem is now typed as NetworkRequest | ConsoleMessage
+ * ```
+ */
+export function validateDetailsItem(item, type) {
+    if (!item || typeof item !== 'object') {
+        throw new CommandError('Invalid item data: expected an object', { suggestion: 'This may indicate corrupted data from the daemon' }, EXIT_CODES.SESSION_FILE_ERROR);
+    }
+    if (type === 'network') {
+        if (!isNetworkRequest(item)) {
+            throw new CommandError('Invalid network request data: missing required fields (requestId, url, method, timestamp)', { suggestion: 'The request data may be incomplete or corrupted' }, EXIT_CODES.SESSION_FILE_ERROR);
+        }
+        return item;
+    }
+    if (!isConsoleMessage(item)) {
+        throw new CommandError('Invalid console message data: missing required fields (type, text, timestamp)', { suggestion: 'The console message data may be incomplete or corrupted' }, EXIT_CODES.SESSION_FILE_ERROR);
+    }
+    return item;
+}
+//# sourceMappingURL=typeGuards.js.map

package/dist/utils/typeGuards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"typeGuards.js","sourceRoot":"","sources":["../../src/utils/typeGuards.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAElD;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACxC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,MAAM,GAAG,KAAgC,CAAC;IAEhD,OAAO,CACL,OAAO,MAAM,CAAC,WAAW,CAAC,KAAK,QAAQ;QACvC,OAAO,MAAM,CAAC,KAAK,CAAC,KAAK,QAAQ;QACjC,OAAO,MAAM,CAAC,QAAQ,CAAC,KAAK,QAAQ;QACpC,OAAO,MAAM,CAAC,WAAW,CAAC,KAAK,QAAQ,CACxC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACxC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,MAAM,GAAG,KAAgC,CAAC;IAEhD,OAAO,CACL,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,QAAQ;QAClC,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,QAAQ;QAClC,OAAO,MAAM,CAAC,WAAW,CAAC,KAAK,QAAQ,CACxC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,mBAAmB,CACjC,IAAa,EACb,IAA2B;IAE3B,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QACtC,MAAM,IAAI,YAAY,CACpB,uCAAuC,EACvC,EAAE,UAAU,EAAE,kDAAkD,EAAE,EAClE,UAAU,CAAC,kBAAkB,CAC9B,CAAC;IACJ,CAAC;IAED,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,EAAE,CAAC;YAC5B,MAAM,IAAI,YAAY,CACpB,2FAA2F,EAC3F,EAAE,UAAU,EAAE,iDAAiD,EAAE,EACjE,UAAU,CAAC,kBAAkB,CAC9B,CAAC;QACJ,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,YAAY,CACpB,+EAA+E,EAC/E,EAAE,UAAU,EAAE,yDAAyD,EAAE,EACzE,UAAU,CAAC,kBAAkB,CAC9B,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser-debugger-cli",
-  "version": "0.6.6",
+  "version": "0.6.8",
   "description": "DevTools telemetry in your terminal. For humans and agents. Direct WebSocket to Chrome's debugging port.",
   "type": "module",
   "bin": {