browser-debugger-cli 0.12.0 → 0.14.0

package/dist/utils/directories.js

@@ -0,0 +1,88 @@
+/**
+ * Checks for a directory bdg is about to create and write (the session
+ * directory, a Chrome profile) before it touches it: `fs.mkdirSync` with
+ * `recursive` spins forever on Linux pseudo-filesystems (`/proc/x` kept a
+ * start at full CPU until SIGKILL), and a profile Chrome cannot use wedges
+ * the session.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+/** Pseudo-filesystems no directory can be created on */
+const PSEUDO_FILESYSTEM = /^\/(proc|sys)(\/|$)/;
+/**
+ * Nearest path at or above `dir` that exists.
+ *
+ * @param dir - Absolute path
+ * @returns The path itself, or its nearest existing ancestor
+ */
+function nearestExisting(dir) {
+    let current = dir;
+    while (!fs.existsSync(current)) {
+        const parent = path.dirname(current);
+        if (parent === current)
+            return current;
+        current = parent;
+    }
+    return current;
+}
+/**
+ * Why `dir` cannot be created or written: it (or the path to it) is on a
+ * pseudo-filesystem, a part of it is a file, or its nearest existing
+ * directory is not writable.
+ *
+ * @param dir - Directory path (resolved against the working directory)
+ * @returns The problem, or null when the directory can be used
+ */
+export function directoryProblem(dir) {
+    const resolved = path.resolve(dir);
+    const existing = nearestExisting(resolved);
+    let real;
+    try {
+        real = fs.realpathSync(existing);
+    }
+    catch (error) {
+        return { reason: error.code ?? String(error), denied: false };
+    }
+    if (PSEUDO_FILESYSTEM.test(resolved) || PSEUDO_FILESYSTEM.test(real)) {
+        const root = (PSEUDO_FILESYSTEM.exec(resolved) ?? PSEUDO_FILESYSTEM.exec(real))?.[0] ?? '';
+        return { reason: `${root.replace(/\/$/, '')} is a pseudo-filesystem`, denied: false };
+    }
+    if (!fs.statSync(real).isDirectory()) {
+        return {
+            reason: existing === resolved ? 'it is a file' : `${existing} is a file`,
+            denied: false,
+        };
+    }
+    try {
+        fs.accessSync(real, fs.constants.W_OK);
+    }
+    catch (error) {
+        const code = error.code ?? String(error);
+        return { reason: `${existing} is not writable (${code})`, denied: true };
+    }
+    return null;
+}
+/**
+ * Create a directory (and its parents) after {@link directoryProblem} found
+ * nothing wrong, so a pseudo-filesystem fails at once instead of spinning.
+ *
+ * @param dir - Directory to create
+ * @param mode - Permissions of the directories created
+ * @throws Error with `code` `EPSEUDOFS` (pseudo-filesystem), `ENOTDIR` (a
+ *   file on the path), `EACCES` (not writable), or the `mkdir` error
+ */
+export function makeDirectory(dir, mode) {
+    if (fs.existsSync(dir))
+        return;
+    const problem = directoryProblem(dir);
+    if (problem) {
+        const code = problem.denied
+            ? 'EACCES'
+            : /pseudo-filesystem/.test(problem.reason)
+                ? 'EPSEUDOFS'
+                : 'ENOTDIR';
+        throw Object.assign(new Error(problem.reason), { code });
+    }
+    fs.mkdirSync(dir, { recursive: true, ...(mode !== undefined && { mode }) });
+}
+//# sourceMappingURL=directories.js.map

package/dist/utils/display.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Whether Chrome can show a window, which decides the default of
+ * `--headless`.
+ */
+/**
+ * Whether a display is available for Chrome's window: on Linux an X11 or
+ * Wayland display (`DISPLAY`, `WAYLAND_DISPLAY`; WSLg sets them too), on
+ * macOS the desktop unless the shell came in over SSH (`SSH_CONNECTION`,
+ * `SSH_TTY`) or runs in CI (`CI`, unless `false` or `0`). Servers, containers and CI stay headless.
+ *
+ * @param env - Environment variables
+ * @param platform - Operating system (`process.platform`)
+ * @returns True when Chrome should show a window by default
+ */
+export declare function hasDisplay(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): boolean;
+//# sourceMappingURL=display.d.ts.map

package/dist/utils/display.js

@@ -0,0 +1,42 @@
+/**
+ * Whether Chrome can show a window, which decides the default of
+ * `--headless`.
+ */
+/**
+ * Whether an environment variable is set and not empty.
+ *
+ * @param env - Environment variables
+ * @param name - Variable name
+ * @returns True when set to a non-empty value
+ */
+function isSet(env, name) {
+    const value = env[name];
+    return value !== undefined && value !== '';
+}
+/**
+ * Whether the environment says it is CI: `CI` set to anything but `false`
+ * or `0` (`CI=false` is how a CI flag is turned off).
+ *
+ * @param env - Environment variables
+ * @returns True in CI
+ */
+function isCi(env) {
+    return isSet(env, 'CI') && !['false', '0'].includes(env['CI']?.toLowerCase() ?? '');
+}
+/**
+ * Whether a display is available for Chrome's window: on Linux an X11 or
+ * Wayland display (`DISPLAY`, `WAYLAND_DISPLAY`; WSLg sets them too), on
+ * macOS the desktop unless the shell came in over SSH (`SSH_CONNECTION`,
+ * `SSH_TTY`) or runs in CI (`CI`, unless `false` or `0`). Servers, containers and CI stay headless.
+ *
+ * @param env - Environment variables
+ * @param platform - Operating system (`process.platform`)
+ * @returns True when Chrome should show a window by default
+ */
+export function hasDisplay(env = process.env, platform = process.platform) {
+    if (platform === 'darwin') {
+        return !isSet(env, 'SSH_CONNECTION') && !isSet(env, 'SSH_TTY') && !isCi(env);
+    }
+    return isSet(env, 'DISPLAY') || isSet(env, 'WAYLAND_DISPLAY');
+}
+//# sourceMappingURL=display.js.map

package/dist/utils/exitCodes.d.ts

@@ -53,6 +53,7 @@ export declare const EXIT_CODES: {
     readonly UNHANDLED_EXCEPTION: 104;
     readonly SIGNAL_HANDLER_ERROR: 105;
     readonly SESSION_START_FAILURE: 106;
+    readonly PAGE_CRASHED: 107;
     readonly SOFTWARE_ERROR: 110;
     readonly INTERRUPTED: 130;
     readonly TERMINATED: 143;

package/dist/utils/exitCodes.js

@@ -53,6 +53,7 @@ export const EXIT_CODES = {
     UNHANDLED_EXCEPTION: 104,
     SIGNAL_HANDLER_ERROR: 105,
     SESSION_START_FAILURE: 106,
+    PAGE_CRASHED: 107,
     SOFTWARE_ERROR: 110,
     INTERRUPTED: 130,
     TERMINATED: 143,
@@ -165,6 +166,11 @@ export const EXIT_CODE_REGISTRY = [
         name: 'SESSION_START_FAILURE',
         description: 'Session failed to start (Chrome launch or CDP connection)',
     },
+    {
+        code: EXIT_CODES.PAGE_CRASHED,
+        name: 'PAGE_CRASHED',
+        description: 'The page crashed (its renderer is gone); bdg page reload brings it back',
+    },
     {
         code: EXIT_CODES.SOFTWARE_ERROR,
         name: 'SOFTWARE_ERROR',

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/process.d.ts

@@ -52,4 +52,16 @@ export declare function killChromeProcess(pid: number, signal?: NodeJS.Signals):
  * @returns Command line, or null if unavailable (process gone, or unsupported platform)
  */
 export declare function getProcessCommand(pid: number): string | null;
+/** A running process and its command line */
+export interface ProcessEntry {
+    pid: number;
+    command: string;
+}
+/**
+ * Every running process with its command line: from `/proc` on Linux
+ * (minimal containers' BusyBox `ps` lacks `-o`), else from `ps` (macOS).
+ *
+ * @returns Processes, empty when they cannot be listed (Windows)
+ */
+export declare function listProcesses(): ProcessEntry[];
 //# sourceMappingURL=process.d.ts.map

package/dist/utils/process.js

@@ -120,4 +120,29 @@ export function getProcessCommand(pid) {
     const command = result.stdout.trim();
     return command.length > 0 ? command : null;
 }
+/**
+ * Every running process with its command line: from `/proc` on Linux
+ * (minimal containers' BusyBox `ps` lacks `-o`), else from `ps` (macOS).
+ *
+ * @returns Processes, empty when they cannot be listed (Windows)
+ */
+export function listProcesses() {
+    if (process.platform === 'win32')
+        return [];
+    if (fs.existsSync('/proc/self/cmdline')) {
+        return fs
+            .readdirSync('/proc')
+            .filter((name) => /^\d+$/.test(name))
+            .map((name) => ({ pid: Number(name), command: getProcessCommand(Number(name)) ?? '' }))
+            .filter((entry) => entry.command !== '');
+    }
+    const result = spawnSync('ps', ['-A', '-ww', '-o', 'pid=,command='], { encoding: 'utf-8' });
+    if (result.error || result.status !== 0)
+        return [];
+    return result.stdout
+        .split('\n')
+        .map((line) => /^\s*(\d+)\s+(.*)$/.exec(line))
+        .filter((match) => match !== null)
+        .map(([, pid, command]) => ({ pid: Number(pid), command: command ?? '' }));
+}
 //# sourceMappingURL=process.js.map

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.12.0",
+  "version": "0.14.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'",