browser-debugger-cli 0.14.0 → 0.16.0

package/dist/ui/messages/networkMessages.js

@@ -15,18 +15,41 @@ function megabytes(bytes) {
     return `${Math.round(bytes / (1024 * 1024))} MB`;
 }
 /**
- * Why a stored response body was replaced by a placeholder (shown by
- * `bdg details network <id>` as `bodyNotCaptured`).
+ * Why a stored request or response body was replaced by a placeholder
+ * (shown by `bdg details network <id>` as `requestBodyNotCaptured` or
+ * `bodyNotCaptured`).
  *
  * @param budgetBytes - Total body budget of the session
- * @returns e.g. `evicted: total body budget (bdg keeps the newest 100 MB of response bodies)`
+ * @returns e.g. `evicted: total body budget (bdg keeps the newest 100 MB of request and response bodies)`
  */
 export function bodyEvictedReason(budgetBytes) {
-    return `evicted: total body budget (bdg keeps the newest ${megabytes(budgetBytes)} of response bodies)`;
+    return `evicted: total body budget (bdg keeps the newest ${megabytes(budgetBytes)} of request and response bodies)`;
+}
+/**
+ * Why a response body is missing when Chrome no longer had it
+ * (`Network.getResponseBody` failed with "No resource with given identifier
+ * found" or "No data found for resource with given identifier"), shown by
+ * `bdg details network <id>` as `bodyNotCaptured` and in the HAR as the
+ * content comment.
+ *
+ * @returns Reason text
+ */
+export function bodyGoneReason() {
+    return 'Chrome no longer had the body (its network buffer evicted it, or the request was cancelled)';
+}
+/**
+ * Why a response body is missing when `Network.getResponseBody` failed for
+ * another reason (a CDP timeout, the connection closing mid-fetch).
+ *
+ * @param errorMessage - The error Chrome or the connection gave
+ * @returns e.g. `Chrome did not return the body: CDP command timeout`
+ */
+export function bodyFetchFailedReason(errorMessage) {
+    return `Chrome did not return the body: ${errorMessage}`;
 }
 /**
  * Note that the session dropped its oldest requests or evicted its oldest
- * response bodies at its limits.
+ * request and response bodies at its limits.
  *
  * @param counts - Requests dropped and bodies evicted
  * @returns e.g. `⚠ 2000 older network requests were dropped: bdg keeps the newest 10000`;
@@ -35,7 +58,7 @@ export function bodyEvictedReason(budgetBytes) {
 export function networkEvictedNote(counts) {
     const { requestsDropped, bodiesEvicted } = counts;
     const requests = pluralize(requestsDropped, 'older network request');
-    const bodies = pluralize(bodiesEvicted, 'older response body', 'older response bodies');
+    const bodies = pluralize(bodiesEvicted, 'older request/response body', 'older request/response bodies');
     const budget = megabytes(MAX_TOTAL_BODY_BYTES);
     if (requestsDropped > 0 && bodiesEvicted > 0) {
         return `⚠ ${requests} dropped, ${bodies} evicted: bdg keeps the newest ${MAX_NETWORK_REQUESTS} requests and ${budget} of bodies`;
@@ -82,4 +105,25 @@ export function headerRepeatedNote(count) {
 export function localProxyNote() {
     return '(loopback; likely a local proxy)';
 }
+/**
+ * HAR log comment of a sanitized export.
+ *
+ * @returns Comment naming what was redacted and the flag that keeps it
+ */
+export function harSanitizedComment() {
+    return 'Sanitized by bdg: values of auth, cookie, API key, token and session headers, cookies, credential query parameters in URLs, password/token/secret fields of JSON and form request and response bodies and WebSocket messages (also truncated JSON, JSON encoded in strings, socket.io, SockJS, server-sent events, NDJSON, and base64 bodies and binary messages that are UTF-8 text), and any JWT (also inside longer strings and form values) are [redacted] in place (by name, so some harmless values are too); everything else stays byte for byte. Not sanitized: other binary data, text that is not JSON or a form, and non-JSON syntax (single quotes, unquoted keys, JSONP, bare values with spaces); a body that could not be sanitized is [redacted] whole. Export with --include-sensitive to keep everything';
+}
+/**
+ * Success message of `bdg network har`.
+ *
+ * @param result - Export result
+ * @returns e.g. `✓ Exported 4 requests to /tmp/out.har` and a line on sanitization
+ */
+export function harExportedMessage(result) {
+    const filterNote = result.filtered ? ' (filtered)' : '';
+    const note = result.sanitized
+        ? 'Credentials sanitized (auth/cookie/API key/token headers, cookies, URL tokens, password and token fields of bodies and WebSocket messages are [redacted]); --include-sensitive keeps them'
+        : '⚠ Includes credentials (--include-sensitive): share this file with care';
+    return `✓ Exported ${result.entries} requests${filterNote} to ${result.file}\n  ${note}`;
+}
 //# sourceMappingURL=networkMessages.js.map

package/dist/ui/messages/session.d.ts

@@ -88,6 +88,14 @@ export declare function endedSessionText(label: string, end: {
     reason: string;
     endedAt: number;
 }): string;
+/**
+ * A session whose directory is not safe to use, for `bdg sessions`.
+ *
+ * @param label - Session name as listed
+ * @param why - Untrusted directory and why
+ * @returns One line
+ */
+export declare function untrustedSessionText(label: string, why: string): string;
 /**
  * Note after a failed start or a stop whose daemon had not exited when bdg stopped waiting.
  *

package/dist/ui/messages/session.js

@@ -101,6 +101,16 @@ export function lastSessionEndText(end) {
 export function endedSessionText(label, end) {
     return `${label} ended ${sessionEndText(end)}`;
 }
+/**
+ * A session whose directory is not safe to use, for `bdg sessions`.
+ *
+ * @param label - Session name as listed
+ * @param why - Untrusted directory and why
+ * @returns One line
+ */
+export function untrustedSessionText(label, why) {
+    return `${label}: ${why}`;
+}
 /**
  * When and why a session ended without `bdg stop`.
  *

package/dist/utils/async.d.ts

@@ -2,11 +2,12 @@
  * Async utilities for common patterns.
  */
 /**
- * Delay execution for a specified duration.
+ * Delay execution for a specified duration, ending early when `signal` aborts.
  *
  * @param ms - Milliseconds to delay
+ * @param signal - Optional abort signal (the delay resolves, not rejects, on abort)
  */
-export declare function delay(ms: number): Promise<void>;
+export declare function delay(ms: number, signal?: AbortSignal): Promise<void>;
 /**
  * Wait for a promise, giving up after a time; the timer is cleared either way.
  *

package/dist/utils/async.js

@@ -2,12 +2,25 @@
  * Async utilities for common patterns.
  */
 /**
- * Delay execution for a specified duration.
+ * Delay execution for a specified duration, ending early when `signal` aborts.
  *
  * @param ms - Milliseconds to delay
+ * @param signal - Optional abort signal (the delay resolves, not rejects, on abort)
  */
-export function delay(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
+export function delay(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal?.aborted) {
+            resolve();
+            return;
+        }
+        const done = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', done);
+            resolve();
+        };
+        const timer = setTimeout(done, ms);
+        signal?.addEventListener('abort', done, { once: true });
+    });
 }
 /**
  * Wait for a promise, giving up after a time; the timer is cleared either way.

package/dist/utils/atomicFile.d.ts

@@ -38,12 +38,13 @@ export declare class AtomicFileWriter {
      *
      * @param filePath - Target file path
      * @param data - Data to write
-     * @param options - Write options
+     * @param options - Write options (`mode`: permissions of the new file, less the umask)
      * @returns Promise that resolves when write completes
      * @throws Error if write operation fails
      */
     static writeAsync(filePath: string, data: string, options?: {
         encoding?: BufferEncoding;
+        mode?: number;
     }): Promise<void>;
     /**
      * Write binary data (Buffer) to a file atomically (asynchronous).

package/dist/utils/atomicFile.js

@@ -59,14 +59,17 @@ export class AtomicFileWriter {
      *
      * @param filePath - Target file path
      * @param data - Data to write
-     * @param options - Write options
+     * @param options - Write options (`mode`: permissions of the new file, less the umask)
      * @returns Promise that resolves when write completes
      * @throws Error if write operation fails
      */
     static async writeAsync(filePath, data, options = {}) {
         const tmpPath = this.getTempPath(filePath);
         try {
-            await fs.promises.writeFile(tmpPath, data, { encoding: options.encoding ?? 'utf-8' });
+            await fs.promises.writeFile(tmpPath, data, {
+                encoding: options.encoding ?? 'utf-8',
+                ...(options.mode !== undefined && { mode: options.mode }),
+            });
             await fs.promises.rename(tmpPath, filePath);
         }
         catch (error) {

package/dist/utils/directories.d.ts

@@ -31,4 +31,45 @@ export declare function directoryProblem(dir: string): DirectoryProblem | null;
  *   file on the path), `EACCES` (not writable), or the `mkdir` error
  */
 export declare function makeDirectory(dir: string, mode?: number): void;
+/**
+ * Kind of untrusted directory: a symlink, not a directory, another user's,
+ * a shared sticky directory such as `/tmp` (others may create entries in
+ * it), or writable by others
+ */
+export type DirTrustKind = 'symlink' | 'not-directory' | 'owner' | 'shared' | 'writable';
+/** Why a directory cannot be trusted */
+export interface DirTrustProblem {
+    /** e.g. `owned by uid 1001`, `writable by others (mode 777)` */
+    reason: string;
+    kind: DirTrustKind;
+}
+/** Options of {@link dirTrustProblem} */
+export interface DirTrustOptions {
+    /**
+     * Accept a directory its group may write to (only others' write access is
+     * refused): under umask 002, common with per-user groups, directories are
+     * created 0775 and the group holds only the user
+     */
+    allowGroupWrite?: boolean;
+}
+/**
+ * Whether a path is a directory the current user can trust: a real directory
+ * (not a symlink), owned by the user, not writable by group or others (by
+ * others only, with `allowGroupWrite`).
+ *
+ * @param dir - Existing path
+ * @param options - What else to accept
+ * @returns Why it cannot be trusted, or null if it can
+ * @throws Error from `lstat` (e.g. `ENOENT` for a missing path)
+ */
+export declare function dirTrustProblem(dir: string, options?: DirTrustOptions): DirTrustProblem | null;
+/**
+ * Strict form of {@link dirTrustProblem}: not a symlink, owned by the user,
+ * not writable by group or others.
+ *
+ * @param dir - Existing path
+ * @returns Why it cannot be trusted, or null if it can
+ * @throws Error from `lstat` (e.g. `ENOENT` for a missing path)
+ */
+export declare function untrustedDirReason(dir: string): string | null;
 //# sourceMappingURL=directories.d.ts.map

package/dist/utils/directories.js

@@ -85,4 +85,52 @@ export function makeDirectory(dir, mode) {
     }
     fs.mkdirSync(dir, { recursive: true, ...(mode !== undefined && { mode }) });
 }
+/** Permission bits that let group or others write */
+const GROUP_OTHER_WRITE = 0o022;
+/** Permission bit that lets others (not the group) write */
+const OTHER_WRITE = 0o002;
+/** Sticky bit: a shared directory like `/tmp` where only owners remove their entries */
+const STICKY = 0o1000;
+/**
+ * Whether a path is a directory the current user can trust: a real directory
+ * (not a symlink), owned by the user, not writable by group or others (by
+ * others only, with `allowGroupWrite`).
+ *
+ * @param dir - Existing path
+ * @param options - What else to accept
+ * @returns Why it cannot be trusted, or null if it can
+ * @throws Error from `lstat` (e.g. `ENOENT` for a missing path)
+ */
+export function dirTrustProblem(dir, options = {}) {
+    const stat = fs.lstatSync(dir);
+    const problem = (reason, kind) => ({ reason, kind });
+    if (stat.isSymbolicLink())
+        return problem('it is a symbolic link', 'symlink');
+    if (!stat.isDirectory())
+        return problem('not a directory', 'not-directory');
+    const uid = process.getuid?.();
+    if (uid !== undefined && stat.uid !== uid)
+        return problem(`owned by uid ${stat.uid}`, 'owner');
+    if (process.platform === 'win32')
+        return null;
+    const writeBits = options.allowGroupWrite ? OTHER_WRITE : GROUP_OTHER_WRITE;
+    if ((stat.mode & writeBits) === 0)
+        return null;
+    const mode = (stat.mode & 0o7777).toString(8);
+    if ((stat.mode & STICKY) !== 0 && (stat.mode & OTHER_WRITE) !== 0) {
+        return problem(`a shared sticky directory (mode ${mode})`, 'shared');
+    }
+    return problem(`writable by others (mode ${mode})`, 'writable');
+}
+/**
+ * Strict form of {@link dirTrustProblem}: not a symlink, owned by the user,
+ * not writable by group or others.
+ *
+ * @param dir - Existing path
+ * @returns Why it cannot be trusted, or null if it can
+ * @throws Error from `lstat` (e.g. `ENOENT` for a missing path)
+ */
+export function untrustedDirReason(dir) {
+    return dirTrustProblem(dir)?.reason ?? null;
+}
 //# sourceMappingURL=directories.js.map

package/dist/utils/http.d.ts

@@ -37,6 +37,13 @@ export interface FetchCDPTargetsOptions {
  * - Network errors are logged to help diagnose Chrome connectivity issues
  */
 export declare function fetchCDPTargets(port?: number, logger?: Logger, options?: FetchCDPTargetsOptions): Promise<CDPTarget[]>;
+/**
+ * Options for a DevTools endpoint probe.
+ */
+export interface DevToolsProbeOptions extends FetchCDPTargetsOptions {
+    /** Ends a pending request early (the probe then reports `unreachable`) */
+    signal?: AbortSignal | undefined;
+}
 /**
  * What answers on a DevTools HTTP endpoint: a Chrome (with its browser-level
  * WebSocket URL), an HTTP server that is not DevTools, or nothing.
@@ -54,19 +61,19 @@ export type DevToolsProbe = {
  *
  * @param port - Chrome debugging port
  * @param logger - Optional logger for debug output
- * @param options - Host, HTTPS and request timeout
+ * @param options - Host, HTTPS, request timeout and abort signal
  * @returns What answered
  */
-export declare function probeDevToolsEndpoint(port: number, logger?: Logger, options?: FetchCDPTargetsOptions): Promise<DevToolsProbe>;
+export declare function probeDevToolsEndpoint(port: number, logger?: Logger, options?: DevToolsProbeOptions): Promise<DevToolsProbe>;
 /**
  * The browser-level DevTools WebSocket URL of a Chrome (`/json/version`).
  *
  * @param port - Chrome debugging port
  * @param logger - Optional logger for debug output
- * @param options - Host and HTTPS
+ * @param options - Host, HTTPS and abort signal
  * @returns The URL, or null if no Chrome answered
  */
-export declare function fetchBrowserWsUrl(port: number, logger?: Logger, options?: Pick<FetchCDPTargetsOptions, 'host' | 'secure'>): Promise<string | null>;
+export declare function fetchBrowserWsUrl(port: number, logger?: Logger, options?: Pick<DevToolsProbeOptions, 'host' | 'secure' | 'signal'>): Promise<string | null>;
 /**
  * Fetch specific CDP target by ID from Chrome's HTTP API.
  *

package/dist/utils/http.js

@@ -67,15 +67,17 @@ export async function fetchCDPTargets(port = DEFAULT_CDP_PORT, logger, options)
  *
  * @param port - Chrome debugging port
  * @param logger - Optional logger for debug output
- * @param options - Host, HTTPS and request timeout
+ * @param options - Host, HTTPS, request timeout and abort signal
  * @returns What answered
  */
 export async function probeDevToolsEndpoint(port, logger, options) {
     const url = `${options?.secure ? 'https' : 'http'}://${options?.host ?? HTTP_LOCALHOST}:${port}/json/version`;
     const timeoutMs = options?.timeoutMs ?? CDP_HTTP_TIMEOUT_MS;
+    const timeout = AbortSignal.timeout(timeoutMs);
+    const signal = options?.signal ? AbortSignal.any([timeout, options.signal]) : timeout;
     let response;
     try {
-        response = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
+        response = await fetch(url, { signal });
     }
     catch (error) {
         logger?.debug(`Chrome version request failed: ${getErrorMessage(error)} (${url})`);
@@ -97,7 +99,7 @@ export async function probeDevToolsEndpoint(port, logger, options) {
  *
  * @param port - Chrome debugging port
  * @param logger - Optional logger for debug output
- * @param options - Host and HTTPS
+ * @param options - Host, HTTPS and abort signal
  * @returns The URL, or null if no Chrome answered
  */
 export async function fetchBrowserWsUrl(port, logger, options) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "browser-debugger-cli",
-  "version": "0.14.0",
-  "description": "DevTools telemetry in your terminal. For humans and agents. Direct WebSocket to Chrome's debugging port.",
+  "version": "0.16.0",
+  "description": "Let Claude Code and other coding agents drive and debug Chrome from the shell. DOM, network, console and raw CDP as short commands, no screenshots and no MCP needed.",
   "type": "module",
   "bin": {
     "bdg": "dist/index.js"
@@ -37,10 +37,24 @@
   "keywords": [
     "cdp",
     "chrome-devtools-protocol",
+    "chrome",
+    "devtools",
+    "debugging",
     "browser",
-    "telemetry",
+    "browser-automation",
+    "headless-chrome",
     "cli",
-    "devtools"
+    "claude",
+    "claude-code",
+    "coding-agent",
+    "ai-agent",
+    "agent-skill",
+    "codex",
+    "css",
+    "figma",
+    "telemetry",
+    "puppeteer-alternative",
+    "playwright-alternative"
   ],
   "license": "MIT",
   "dependencies": {