browser-debugger-cli 0.13.0 → 0.15.0

package/dist/ui/messages/commands.js

@@ -193,16 +193,14 @@ export function valueMismatchWarning(mismatch) {
  */
 export const CLICK_NOT_RECEIVED_WARNING = 'The click may not have reached the element: the page saw no mouse press (the browser may be showing a dialog or bubble that captures input)';
 /**
- * Note under a shortened list of matches.
+ * Note under a shortened human list whose JSON output lists more, up to a cap.
  *
- * @param hidden - Matches not listed
- * @param jsonLimit - How many JSON output lists, when it leaves some out too
- * @returns e.g. "... and 1174 more (use --json for all)",
- *   "... and 8980 more (--json lists the first 100)"
+ * @param hidden - Items not listed
+ * @param jsonLimit - Most items the JSON output lists
+ * @returns e.g. "... and 8980 more (--json lists up to 100)"
  */
 export function moreMatchesNote(hidden, jsonLimit) {
-    const where = jsonLimit === undefined ? 'use --json for all' : `--json lists the first ${jsonLimit}`;
-    return `... and ${hidden} more (${where})`;
+    return `... and ${hidden} more (--json lists up to ${jsonLimit})`;
 }
 /**
  * Note under `dom query` matches cut by `--limit`.
@@ -225,6 +223,24 @@ export function queryMoreMatchesNote(omitted, indexed) {
 export function queryViewportCheckedNote(checked) {
     return `Visibility is checked for the first ${checked} matches only; ${sessionCommand('bdg dom layout <index>')} checks any of them`;
 }
+/**
+ * First line under an accessibility tree cut by `--limit` or `--depth`.
+ *
+ * @param listed - Nodes listed
+ * @returns e.g. "Showing the first 50 nodes (text boxes and repeated text left out)"
+ */
+export function a11yTreeShownNote(listed) {
+    return `Showing the first ${listed} nodes (text boxes and repeated text left out)`;
+}
+/**
+ * How to see the rest of an accessibility tree cut by `--limit` or `--depth`.
+ *
+ * @param omitted - Nodes left out
+ * @returns e.g. "51391 more: --limit 0 lists all, --depth <n> limits the levels, or search with bdg dom a11y query \"role:<role>\""
+ */
+export function a11yTreeMoreNote(omitted) {
+    return `${omitted} more: --limit 0 lists all, --depth <n> limits the levels, or search with bdg dom a11y query "role:<role>"`;
+}
 /**
  * Note under a list of a11y query matches cut by `--limit`.
  *
@@ -585,10 +601,13 @@ export function coverText(cover, transparent) {
  * Note when `bdg dom inspect` could not read the element's matched rules, so
  * no hints, rules or why were computed.
  *
- * @param reason - `timeout` (very large stylesheets) or `failed` (Chrome reported an error)
+ * @param reason - `timeout` (very large stylesheets), `failed` (Chrome reported
+ *   an error) or `skipped` (hints not read: an earlier read on this page timed out)
  * @returns Note
  */
 export function inspectCascadeNote(reason) {
+    if (reason === 'skipped')
+        return "hints skipped: this page's stylesheets are slow to read (--rules waits 5 s)";
     return reason === 'timeout'
         ? "CSS rules not read: the page's stylesheets took too long (hints wait 1 s; --rules and --why 5 s)"
         : 'CSS rules not read: Chrome could not report the rules matching this element';
@@ -1279,4 +1298,13 @@ Examples:
 export function helpJsonDetailsNote() {
     return 'Option behaviors, defaults, choices and examples: bdg <command> --help --json (e.g. bdg dom query --help --json). Everything at once: bdg --help --json --full';
 }
+/**
+ * Pointer after a value cut for human output.
+ *
+ * @param count - Characters left out
+ * @returns e.g. `… 299800 more chars (use --full)`
+ */
+export function moreCharsNote(count) {
+    return `… ${count} more chars (use --full)`;
+}
 //# sourceMappingURL=commands.js.map

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

@@ -3,6 +3,30 @@
  *
  * User-facing messages for the network list command output and formatting.
  */
+/**
+ * Why a stored response body was replaced by a placeholder (shown by
+ * `bdg details network <id>` as `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)`
+ */
+export declare function bodyEvictedReason(budgetBytes: number): string;
+/** What a session's network capture let go at its limits */
+export interface NetworkEvictionCounts {
+    /** Oldest finished requests dropped at the request cap */
+    requestsDropped: number;
+    /** Oldest response bodies evicted at the body budget */
+    bodiesEvicted: number;
+}
+/**
+ * Note that the session dropped its oldest requests or evicted its oldest
+ * 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`;
+ *   undefined when nothing was let go
+ */
+export declare function networkEvictedNote(counts: NetworkEvictionCounts): string | undefined;
 /**
  * Generate message for following network output.
  *
@@ -29,4 +53,30 @@ export declare function headerRepeatedNote(count: number): string;
  * @returns Note text
  */
 export declare function localProxyNote(): string;
+/**
+ * HAR log comment of a sanitized export.
+ *
+ * @returns Comment naming what was redacted and the flag that keeps it
+ */
+export declare function harSanitizedComment(): string;
+/**
+ * Result of a HAR export to a file.
+ */
+export interface HarExportSummary {
+    /** Absolute path written */
+    file: string;
+    /** Requests exported */
+    entries: number;
+    /** Whether --filter left requests out */
+    filtered: boolean;
+    /** Whether credentials were redacted */
+    sanitized: boolean;
+}
+/**
+ * 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 declare function harExportedMessage(result: HarExportSummary): string;
 //# sourceMappingURL=networkMessages.d.ts.map

package/dist/ui/messages/networkMessages.js

@@ -3,6 +3,51 @@
  *
  * User-facing messages for the network list command output and formatting.
  */
+import { MAX_NETWORK_REQUESTS, MAX_TOTAL_BODY_BYTES } from '../../constants.js';
+import { pluralize } from '../formatting.js';
+/**
+ * A byte budget in whole megabytes.
+ *
+ * @param bytes - Budget
+ * @returns e.g. `100 MB`
+ */
+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`).
+ *
+ * @param budgetBytes - Total body budget of the session
+ * @returns e.g. `evicted: total body budget (bdg keeps the newest 100 MB of response bodies)`
+ */
+export function bodyEvictedReason(budgetBytes) {
+    return `evicted: total body budget (bdg keeps the newest ${megabytes(budgetBytes)} of response bodies)`;
+}
+/**
+ * Note that the session dropped its oldest requests or evicted its oldest
+ * 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`;
+ *   undefined when nothing was let go
+ */
+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 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`;
+    }
+    if (requestsDropped > 0) {
+        return `⚠ ${requests} ${requestsDropped === 1 ? 'was' : 'were'} dropped: bdg keeps the newest ${MAX_NETWORK_REQUESTS}`;
+    }
+    if (bodiesEvicted > 0) {
+        return `⚠ ${bodies} ${bodiesEvicted === 1 ? 'was' : 'were'} evicted: bdg keeps the newest ${budget} of bodies`;
+    }
+    return undefined;
+}
 /**
  * Generate message for following network output.
  *
@@ -37,4 +82,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, and password/token fields of request bodies are [redacted] (by name, so some harmless values are too); response bodies and WebSocket messages are not sanitized. 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 body fields 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/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

@@ -1,5 +1,12 @@
 import type { CDPTarget } from '../types.js';
 import type { Logger } from '../ui/logging/index.js';
+/**
+ * Timeout for CDP HTTP requests in milliseconds.
+ *
+ * Chrome's HTTP API should respond quickly when running.
+ * A 5-second timeout helps detect when Chrome is not responding.
+ */
+export declare const CDP_HTTP_TIMEOUT_MS = 5000;
 /**
  * Options for CDP HTTP target fetch.
  */
@@ -47,10 +54,10 @@ export type DevToolsProbe = {
  *
  * @param port - Chrome debugging port
  * @param logger - Optional logger for debug output
- * @param options - Host and HTTPS
+ * @param options - Host, HTTPS and request timeout
  * @returns What answered
  */
-export declare function probeDevToolsEndpoint(port: number, logger?: Logger, options?: Pick<FetchCDPTargetsOptions, 'host' | 'secure'>): Promise<DevToolsProbe>;
+export declare function probeDevToolsEndpoint(port: number, logger?: Logger, options?: FetchCDPTargetsOptions): Promise<DevToolsProbe>;
 /**
  * The browser-level DevTools WebSocket URL of a Chrome (`/json/version`).
  *

package/dist/utils/http.js

@@ -6,7 +6,7 @@ import { getErrorMessage } from './errors.js';
  * Chrome's HTTP API should respond quickly when running.
  * A 5-second timeout helps detect when Chrome is not responding.
  */
-const CDP_HTTP_TIMEOUT_MS = 5000;
+export const CDP_HTTP_TIMEOUT_MS = 5000;
 /**
  * Fetch CDP targets from Chrome's HTTP API.
  *
@@ -67,14 +67,15 @@ 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 and HTTPS
+ * @param options - Host, HTTPS and request timeout
  * @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;
     let response;
     try {
-        response = await fetch(url, { signal: AbortSignal.timeout(CDP_HTTP_TIMEOUT_MS) });
+        response = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
     }
     catch (error) {
         logger?.debug(`Chrome version request failed: ${getErrorMessage(error)} (${url})`);

package/dist/utils/strings.d.ts

@@ -11,4 +11,23 @@
  * @returns Truncated text with ellipsis if needed
  */
 export declare function truncateByLength(text: string, maxLength?: number): string;
+/**
+ * A text cut to a maximum length, with its original length when it was cut.
+ */
+export interface CappedText {
+    /** The text, or its first `maxLength` characters */
+    text: string;
+    /** Original length, set only when the text was cut */
+    truncatedFrom?: number;
+}
+/**
+ * Cut a text to its first `maxLength` characters (UTF-16 code units),
+ * keeping the original length (the `truncatedFrom` of JSON output). A
+ * surrogate pair (an emoji) is never split: the cut ends before it.
+ *
+ * @param text - Text to cut
+ * @param maxLength - Characters kept (at most)
+ * @returns The text, with `truncatedFrom` when it was cut
+ */
+export declare function capLength(text: string, maxLength: number): CappedText;
 //# sourceMappingURL=strings.d.ts.map

package/dist/utils/strings.js

@@ -20,4 +20,20 @@ export function truncateByLength(text, maxLength = DEFAULT_MAX_LENGTH) {
     }
     return text.slice(0, maxLength - 1) + '…';
 }
+/**
+ * Cut a text to its first `maxLength` characters (UTF-16 code units),
+ * keeping the original length (the `truncatedFrom` of JSON output). A
+ * surrogate pair (an emoji) is never split: the cut ends before it.
+ *
+ * @param text - Text to cut
+ * @param maxLength - Characters kept (at most)
+ * @returns The text, with `truncatedFrom` when it was cut
+ */
+export function capLength(text, maxLength) {
+    if (text.length <= maxLength)
+        return { text };
+    const lastKept = text.charCodeAt(maxLength - 1);
+    const end = lastKept >= 0xd800 && lastKept <= 0xdbff ? maxLength - 1 : maxLength;
+    return { text: text.slice(0, end), truncatedFrom: text.length };
+}
 //# sourceMappingURL=strings.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser-debugger-cli",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "DevTools telemetry in your terminal. For humans and agents. Direct WebSocket to Chrome's debugging port.",
   "type": "module",
   "bin": {
@@ -27,7 +27,7 @@
     "validate:ts-version": "node -e \"const ts = require('typescript'); const v = ts.version.split('.'); if (parseInt(v[0]) < 5 || (parseInt(v[0]) === 5 && parseInt(v[1]) < 6)) { console.error('Requires TypeScript 5.6+, found:', ts.version); process.exit(1); } else { console.log('✅ TypeScript version:', ts.version); }\"",
     "check": "npm run format:check && npm run type-check && npm run lint",
     "check:enhanced": "npm run format:check && npm run type-check && npm run lint && npm run validate:module-type && npm run validate:ts-version",
-    "test": "tsx --test 'src/**/__tests__/**/!(*.smoke).test.ts'",
+    "test": "tsx --test --test-timeout=120000 'src/**/__tests__/**/!(*.smoke).test.ts'",
     "test:watch": "tsx --test --watch 'src/**/__tests__/**/!(*.smoke).test.ts'",
     "test:coverage": "c8 npm test",
     "test:smoke": "tsx --test --test-concurrency=1 'src/__tests__/smoke/*.smoke.test.ts'",