browser-debugger-cli 0.12.0 → 0.13.0

package/dist/ui/messages/commands.js

@@ -26,6 +26,15 @@ export function chromeClosedMessage(pid) {
 export function orphanedDaemonsCleanedMessage(count) {
     return `Cleaned up ${count} orphaned daemon process${count === 1 ? '' : 'es'}`;
 }
+/**
+ * Where `bdg install-skill` kept the copy it replaced.
+ *
+ * @param path - Backup path, as the user would type it
+ * @returns One line
+ */
+export function skillBackupMessage(path) {
+    return `previous copy kept in ${path}`;
+}
 /**
  * Warning shown when a click falls back from mouse events to `el.click()`.
  *
@@ -195,6 +204,27 @@ export function moreMatchesNote(hidden, jsonLimit) {
     const where = jsonLimit === undefined ? 'use --json for all' : `--json lists the first ${jsonLimit}`;
     return `... and ${hidden} more (${where})`;
 }
+/**
+ * Note under `dom query` matches cut by `--limit`.
+ *
+ * @param omitted - Matches not listed
+ * @param indexed - Matches usable by index, when not all of them
+ * @returns e.g. `... and 49953 more (--limit 0 lists all; indices 0-999 work with other commands)`
+ */
+export function queryMoreMatchesNote(omitted, indexed) {
+    const indices = indexed === undefined ? '' : `; indices 0-${indexed - 1} work with other commands`;
+    return `... and ${omitted} more (--limit 0 lists all${indices})`;
+}
+/**
+ * Note under `dom query` matches listed past those whose viewport position
+ * was checked.
+ *
+ * @param checked - First matches checked
+ * @returns e.g. `Visibility is checked for the first 100 matches only; bdg dom layout <index> checks any of them`
+ */
+export function queryViewportCheckedNote(checked) {
+    return `Visibility is checked for the first ${checked} matches only; ${sessionCommand('bdg dom layout <index>')} checks any of them`;
+}
 /**
  * Note under a list of a11y query matches cut by `--limit`.
  *
@@ -253,6 +283,37 @@ export const LAYOUT_REASONS = {
     /** Joins an invisible reason to the ancestor causing it */
     on: ' on ',
 };
+/** Why an out-of-view text's contrast in `dom audit` is approximate: none of its ancestors paints a background */
+export const AUDIT_OUT_OF_VIEW_RISK = 'only its ancestors were checked';
+/**
+ * `dom audit contrast` note for text that looks below the level but cannot
+ * be measured exactly (over an image, blended, under or over another layer).
+ *
+ * @param count - How many such texts
+ * @returns e.g. `(+12 more may be below it but cannot be measured: text over images or blended layers; check them with bdg dom inspect)`
+ */
+export function auditUncertainContrastNote(count) {
+    return `(+${count} more may be below it but cannot be measured: text over images or blended layers; check them with ${sessionCommand('bdg dom inspect <element>')})`;
+}
+/**
+ * `dom audit animations` note for canvas elements, whose script-drawn
+ * animations it cannot see.
+ *
+ * @param count - Visible canvas elements
+ * @returns e.g. `(+ 2 canvas elements: animations drawn by scripts on them are not listed)`
+ */
+export function auditCanvasNote(count) {
+    return `(+ ${count} canvas ${count === 1 ? 'element' : 'elements'}: animations drawn by scripts on ${count === 1 ? 'it are' : 'them are'} not listed)`;
+}
+/**
+ * A mask over an element, for `dom layout` and `dom inspect`.
+ *
+ * @param masked - The mask, e.g. `mask-image on div.hero`
+ * @returns e.g. `masked by mask-image on div.hero`
+ */
+export function maskedText(masked) {
+    return `masked by ${masked}`;
+}
 /** Start of the off-screen reason of an element a scroll-locked page hides ({@link scrollLockedReason}) */
 const SCROLL_LOCKED_PREFIX = 'page scrolling is locked';
 /**
@@ -391,16 +452,63 @@ export function colorSchemeLabel(scheme, emulated) {
     const source = emulated ? 'emulated' : 'from the system setting';
     return `prefers-color-scheme: ${scheme} (${source})`;
 }
+/**
+ * Suggestion for an action that failed on a page that replaced built-ins
+ * bdg's page scripts use.
+ *
+ * @param replaced - Their dotted names (all are named)
+ * @returns Suggestion naming them and a way around
+ */
+export function brokenByReplacedBuiltinsSuggestion(replaced) {
+    return `The page replaced built-ins bdg's action script uses (${replaced.join(', ')}), which may have broken it; if so, act on the element with ${sessionCommand("bdg dom eval '…'")} instead`;
+}
+/**
+ * Warning on an action when the page replaced built-ins bdg's page scripts
+ * use (polyfills, old frameworks, anti-bot scripts). Names the first four;
+ * the action's `replacedBuiltins` (JSON) lists them all.
+ *
+ * @param replaced - Their dotted names
+ * @returns e.g. `the page replaced built-ins bdg's scripts use (Element.prototype.querySelectorAll); bdg found the element in its own world, but the action runs in the page's and may misbehave`
+ */
+export function replacedBuiltinsWarning(replaced) {
+    const shown = replaced.slice(0, 4).join(', ') +
+        (replaced.length > 4 ? `, +${replaced.length - 4} more (see --json)` : '');
+    return `the page replaced built-ins bdg's scripts use (${shown}); bdg found the element in its own world, but the action runs in the page's and may misbehave`;
+}
 /**
  * First line of `bdg status` for a running session.
  *
- * @param page - URL and title of the page, when the session reported them
- * @returns e.g. `Session active: https://example.com/ — Example Domain`
+ * @param page - URL and title of the page, when the session reported them,
+ *   and when it crashed
+ * @returns e.g. `Session active: https://example.com/ — Example Domain`, with
+ *   a crash warning on a second line
  */
 export function sessionActiveLine(page) {
     if (!page)
         return 'Session active';
-    return `Session active: ${page.url}${page.title ? ` — ${page.title}` : ''}`;
+    const line = `Session active: ${page.url}${page.title ? ` — ${page.title}` : ''}`;
+    return page.crashedAt === undefined ? line : `${line}\n${pageCrashedNote(page.crashedAt)}`;
+}
+/**
+ * Warning that the session's page crashed, for `bdg status`, `bdg peek`,
+ * `bdg console` and `bdg network list`.
+ *
+ * @param crashedAt - When it crashed (epoch ms)
+ * @returns e.g. `⚠ The page crashed at 18:42:10 (renderer gone); bdg page reload brings it back`
+ */
+export function pageCrashedNote(crashedAt) {
+    return `⚠ The page crashed at ${new Date(crashedAt).toLocaleTimeString()} (renderer gone); ${sessionCommand('bdg page reload')} brings it back`;
+}
+/**
+ * Put the page-crashed warning before a view of collected data, when the
+ * page crashed (what is shown was collected before).
+ *
+ * @param body - The view
+ * @param crashedAt - When the page crashed (epoch ms), if it did
+ * @returns The view, after the warning when the page crashed
+ */
+export function withPageCrashedNote(body, crashedAt) {
+    return crashedAt === undefined ? body : `${pageCrashedNote(crashedAt)}\n\n${body}`;
 }
 /**
  * Page dimensions line of `bdg dom layout`.
@@ -524,6 +632,7 @@ export function inspectVisibilityBadges(visibility) {
         visibility.hidden && `[hidden: ${visibility.hidden}]`,
         visibility.offscreen && `[offscreen: ${visibility.offscreen}]`,
         visibility.coveredBy && `[${coverText(visibility.coveredBy, visibility.coverTransparent)}]`,
+        visibility.masked && `[${maskedText(visibility.masked)}]`,
     ].filter((badge) => Boolean(badge));
 }
 /**
@@ -674,6 +783,19 @@ export function dialogConsoleText(dialog) {
     const kind = dialog.type === 'beforeunload' ? 'beforeunload' : `${dialog.type}()`;
     return `${kind} dialog accepted${dialog.message ? `: "${dialog.message}"` : ''}`;
 }
+/**
+ * How far a pointer action scrolled the page to reach its element.
+ *
+ * @param scrolledBy - Page scroll (CSS px)
+ * @returns e.g. `page down 1240px to reach it`, `page right 300px, up 80px to reach it`
+ */
+export function pointerScrollText(scrolledBy) {
+    const parts = [
+        scrolledBy.y !== 0 && `${scrolledBy.y > 0 ? 'down' : 'up'} ${Math.abs(scrolledBy.y)}px`,
+        scrolledBy.x !== 0 && `${scrolledBy.x > 0 ? 'right' : 'left'} ${Math.abs(scrolledBy.x)}px`,
+    ].filter(Boolean);
+    return `page ${parts.join(', ')} to reach it`;
+}
 /** Headline of each pointer action, e.g. "Element Double-clicked" */
 export const POINTER_ACTION_DONE = {
     click: 'Clicked',
@@ -912,13 +1034,17 @@ export function elementTextLine(text) {
  *
  * @param children - First child elements, e.g. `iframe#app`
  * @param count - Number of child elements
- * @returns e.g. `No text; holds 1 element: iframe (see its HTML with --raw)`
+ * @param inShadowRoot - The children are those of its shadow root (`--raw` does not show them)
+ * @returns e.g. `No text; holds 1 element: iframe (see its HTML with --raw)`,
+ *   `No text; its shadow root holds 1 element: button "Close" (see it with bdg dom inspect)`
  */
-export function emptyElementLine(children, count) {
+export function emptyElementLine(children, count, inShadowRoot = false) {
+    const holder = inShadowRoot ? 'its shadow root holds' : 'holds';
     if (count === 0)
-        return 'No text and no child elements';
+        return `No text and no child elements${inShadowRoot ? ' in its shadow root' : ''}`;
     const more = count > children.length ? `, … ${count - children.length} more` : '';
-    return `No text; holds ${pluralize(count, 'element')}: ${children.join(', ')}${more} (see its HTML with --raw)`;
+    const hint = inShadowRoot ? 'see it with bdg dom inspect' : 'see its HTML with --raw';
+    return `No text; ${holder} ${pluralize(count, 'element')}: ${children.join(', ')}${more} (${hint})`;
 }
 /**
  * Note on a screenshot scaled down to keep its image token cost bounded.
@@ -969,6 +1095,27 @@ export function queryNextSteps(index) {
 export function evalFrameLine(url) {
     return `Frame: ${frameUrlLabel(url)}`;
 }
+/**
+ * Warning on a `dom eval` result the browser copied because the page
+ * replaced built-ins bdg's own copy uses.
+ *
+ * @param replaced - Their dotted names (all are named)
+ * @returns e.g. `the page replaced Object.keys, so the browser copied the result: undefined, NaN, functions, DOM nodes, dates, maps and sets inside it show as null or {}`
+ */
+export function evalCopiedByBrowserWarning(replaced) {
+    return `the page replaced ${replaced.join(', ')}, so the browser copied the result: undefined, NaN, functions, DOM nodes, dates, maps and sets inside it show as null or {}`;
+}
+/**
+ * Warning on a `dom eval` result shown as its preview: the page replaced
+ * built-ins bdg's copy uses and the browser could not copy it either (a
+ * cycle or a BigInt inside).
+ *
+ * @param replaced - Their dotted names (all are named)
+ * @returns Warning that the value is a shortened preview
+ */
+export function evalPreviewWarning(replaced) {
+    return `the page replaced ${replaced.join(', ')}, and the result could not be copied (it holds a cycle or a BigInt), so it is shown as a shortened preview string; return a JSON-safe value (e.g. pick the fields you need)`;
+}
 /**
  * Generate warning message.
  *
@@ -1124,4 +1271,12 @@ Examples:
                                   bdg css search --limit 50 -- --brand)
   bdg css search "oklch("         Rules that use oklch colors
   bdg css search ".btn-primary"   Rules of a class, in every stylesheet`;
+/**
+ * `details` field of `bdg --help --json`: where the full help is.
+ *
+ * @returns Note
+ */
+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';
+}
 //# sourceMappingURL=commands.js.map

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

@@ -25,4 +25,28 @@ export declare function stoppedFollowingConsoleMessage(): string;
  * @returns e.g. `[n] are positions in the session's message list; not listed in between: 1 message from another page load (-H lists all)`
  */
 export declare function consoleIndexGapNote(skipped: ConsoleSkipped): string;
+/**
+ * Note that the session dropped its oldest console messages at the limit.
+ *
+ * @param dropped - Messages dropped
+ * @returns e.g. `⚠ 2000 older console messages were dropped: bdg keeps the newest 10000`
+ */
+export declare function consoleDroppedNote(dropped: number): string;
+/**
+ * Error for `bdg details console <n>` with the index of a dropped message.
+ *
+ * @param index - Index asked for
+ * @param dropped - Messages dropped (the first kept has this index)
+ * @returns Message
+ */
+export declare function consoleMessageDroppedError(index: number, dropped: number): string;
+/**
+ * Note under the console summary when it lists only the newest distinct
+ * errors or warnings.
+ *
+ * @param more - Distinct messages not listed
+ * @param level - `error` or `warning`
+ * @returns e.g. `(+120 earlier distinct errors; bdg console --level error --last 0 lists every one)`
+ */
+export declare function consoleMoreGroupsNote(more: number, level: 'error' | 'warning'): string;
 //# sourceMappingURL=consoleMessages.d.ts.map

package/dist/ui/messages/consoleMessages.js

@@ -3,7 +3,9 @@
  *
  * User-facing messages for the console command output and formatting.
  */
+import { MAX_CONSOLE_MESSAGES } from '../../constants.js';
 import { pluralize } from '../formatting.js';
+import { sessionCommand } from './sessionCommand.js';
 /**
  * Generate message for following console output.
  *
@@ -36,4 +38,34 @@ export function consoleIndexGapNote(skipped) {
     ].filter(Boolean);
     return `[n] are positions in the session's message list; not listed in between: ${reasons.join(', ')}`;
 }
+/**
+ * Note that the session dropped its oldest console messages at the limit.
+ *
+ * @param dropped - Messages dropped
+ * @returns e.g. `⚠ 2000 older console messages were dropped: bdg keeps the newest 10000`
+ */
+export function consoleDroppedNote(dropped) {
+    return `⚠ ${pluralize(dropped, 'older console message')} ${dropped === 1 ? 'was' : 'were'} dropped: bdg keeps the newest ${MAX_CONSOLE_MESSAGES}`;
+}
+/**
+ * Error for `bdg details console <n>` with the index of a dropped message.
+ *
+ * @param index - Index asked for
+ * @param dropped - Messages dropped (the first kept has this index)
+ * @returns Message
+ */
+export function consoleMessageDroppedError(index, dropped) {
+    return `Console message ${index} was dropped: bdg keeps the newest ${MAX_CONSOLE_MESSAGES} messages (the oldest kept is ${dropped})`;
+}
+/**
+ * Note under the console summary when it lists only the newest distinct
+ * errors or warnings.
+ *
+ * @param more - Distinct messages not listed
+ * @param level - `error` or `warning`
+ * @returns e.g. `(+120 earlier distinct errors; bdg console --level error --last 0 lists every one)`
+ */
+export function consoleMoreGroupsNote(more, level) {
+    return `(+${more} earlier distinct ${more === 1 ? level : `${level}s`}; ${sessionCommand(`bdg console --level ${level} --last 0`)} lists every one)`;
+}
 //# sourceMappingURL=consoleMessages.js.map

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

@@ -55,6 +55,12 @@ export declare function stoppedFollowingPreviewMessage(): string;
  * @param retryLabel - Human-readable retry interval (e.g. "1s", "500ms")
  */
 export declare function connectionLostRetryMessage(timestamp: string, retryLabel: string): string;
+/**
+ * Follow mode stops because the session it followed ended.
+ *
+ * @returns Message
+ */
+export declare function followedSessionEndedMessage(): string;
 /**
  * Generate follow-mode stop hint.
  *

package/dist/ui/messages/preview.js

@@ -19,7 +19,7 @@ export const PREVIEW_HEADERS = {
  * @returns Single-line tip for basic peek usage
  */
 export function compactTipsMessage() {
-    return `Tip: ${sessionCommand('bdg peek --last 50')} | ${sessionCommand('bdg peek --verbose')}`;
+    return `Tip: ${sessionCommand('bdg peek --last 50')} or ${sessionCommand('bdg peek --verbose')}`;
 }
 /**
  * Generate verbose mode commands section.
@@ -71,6 +71,14 @@ export function stoppedFollowingPreviewMessage() {
 export function connectionLostRetryMessage(timestamp, retryLabel) {
     return `\n[${timestamp}] ⚠️  Connection lost, retrying every ${retryLabel}...`;
 }
+/**
+ * Follow mode stops because the session it followed ended.
+ *
+ * @returns Message
+ */
+export function followedSessionEndedMessage() {
+    return 'The session ended; stopped following';
+}
 /**
  * Generate follow-mode stop hint.
  *

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

@@ -78,7 +78,18 @@ export declare function lastSessionEndText(end: {
     endedAt: number;
 }): string;
 /**
- * Note after a failed start whose daemon had not exited when bdg stopped waiting.
+ * A session that ended without `bdg stop`, for `bdg sessions`.
+ *
+ * @param label - Session name as listed
+ * @param end - How and when it ended
+ * @returns One line
+ */
+export declare function endedSessionText(label: string, end: {
+    reason: string;
+    endedAt: number;
+}): string;
+/**
+ * Note after a failed start or a stop whose daemon had not exited when bdg stopped waiting.
  *
  * @param pid - Daemon PID, when known
  * @param waitedMs - How long bdg waited
@@ -86,7 +97,7 @@ export declare function lastSessionEndText(end: {
  */
 export declare function daemonStillExitingHint(pid: number | undefined, waitedMs: number): string;
 /**
- * What to do about a daemon still shutting down after a failed start.
+ * What to do about a daemon still shutting down after a failed start or a stop.
  *
  * @returns Suggestion
  */

package/dist/ui/messages/session.js

@@ -89,16 +89,35 @@ export function stopFailedError(reason) {
  * @returns One line
  */
 export function lastSessionEndText(end) {
+    return `The last session ended ${sessionEndText(end)}`;
+}
+/**
+ * A session that ended without `bdg stop`, for `bdg sessions`.
+ *
+ * @param label - Session name as listed
+ * @param end - How and when it ended
+ * @returns One line
+ */
+export function endedSessionText(label, end) {
+    return `${label} ended ${sessionEndText(end)}`;
+}
+/**
+ * When and why a session ended without `bdg stop`.
+ *
+ * @param end - How and when it ended
+ * @returns `at <time>: <why>`
+ */
+function sessionEndText(end) {
     const why = {
         crash: 'Chrome crashed or was closed',
         closed: 'its page was closed',
         timeout: 'the --timeout was reached',
     };
     const at = new Date(end.endedAt).toLocaleTimeString();
-    return `The last session ended at ${at}: ${why[end.reason] ?? end.reason}`;
+    return `at ${at}: ${why[end.reason] ?? end.reason}`;
 }
 /**
- * Note after a failed start whose daemon had not exited when bdg stopped waiting.
+ * Note after a failed start or a stop whose daemon had not exited when bdg stopped waiting.
  *
  * @param pid - Daemon PID, when known
  * @param waitedMs - How long bdg waited
@@ -109,7 +128,7 @@ export function daemonStillExitingHint(pid, waitedMs) {
     return `${daemon} was still shutting down after ${waitedMs / 1000}s`;
 }
 /**
- * What to do about a daemon still shutting down after a failed start.
+ * What to do about a daemon still shutting down after a failed start or a stop.
  *
  * @returns Suggestion
  */

package/dist/utils/directories.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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.
+ */
+/** Why a directory cannot be used, and whether it is a permission problem */
+export interface DirectoryProblem {
+    /** e.g. `/proc is a pseudo-filesystem`, `/tmp/x is a file`, `EACCES` */
+    reason: string;
+    /** Permission denied (or a read-only file system) rather than a wrong path */
+    denied: boolean;
+}
+/**
+ * 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 declare function directoryProblem(dir: string): DirectoryProblem | 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 declare function makeDirectory(dir: string, mode?: number): void;
+//# sourceMappingURL=directories.d.ts.map

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/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