browser-debugger-cli 0.14.0 → 0.15.0

package/dist/errors/messages.d.ts

@@ -5,6 +5,7 @@
  */
 import type { DomFrame, PendingRequestInfo } from '../ipc/protocol/commands.js';
 import { type WaitCondition, type WaitSnapshot } from '../runtime/dom/waitCondition.js';
+import { type UntrustedSessionDir } from '../session/paths.js';
 import type { DocumentRequestState, IndexSource } from '../types.js';
 /**
  * Generate "session already running" error message (commands carry
@@ -258,6 +259,13 @@ export declare function invalidSelectorFilterError(selector: string, filter: str
  * @param closest - Most similar existing command path, if any
  */
 export declare function unknownHelpTopicError(topic: string, closest?: string): ErrorWithSuggestion;
+/**
+ * "Did you mean" for one or more close candidates, joined as a sentence.
+ *
+ * @param candidates - Close matches, e.g. ["form", "frames"]
+ * @returns e.g. "Did you mean: form or frames?" or "Did you mean: a, b or c?"
+ */
+export declare function didYouMeanSuggestion(candidates: string[]): string;
 /**
  * Suggestion for a command-line usage error (missing argument, invalid value,
  * unknown option without a close match).
@@ -360,6 +368,21 @@ export declare function sessionDirIsFileError(dir: string): ErrorWithSuggestion;
  * @param reason - File-system error
  */
 export declare function sessionDirNotWritableError(dir: string, reason: string): ErrorWithSuggestion;
+/**
+ * The session directory, or one above it, is not safe to use: another user
+ * could replace the daemon socket or plant files there.
+ *
+ * @param untrusted - Untrusted directory and why
+ */
+export declare function untrustedSessionDirError(untrusted: UntrustedSessionDir): ErrorWithSuggestion;
+/**
+ * The daemon log cannot be opened for writing (a symlink there is refused,
+ * not followed).
+ *
+ * @param logPath - Daemon log path
+ * @param code - File-system error code
+ */
+export declare function daemonLogNotOpenedError(logPath: string, code: string): ErrorWithSuggestion;
 /**
  * The daemon socket path exceeds the OS limit for Unix sockets.
  *

package/dist/errors/messages.js

@@ -3,6 +3,7 @@
  *
  * Centralized location for reusable error messages with consistent formatting.
  */
+import * as os from 'os';
 import * as path from 'path';
 import { countedMatches, } from '../runtime/dom/waitCondition.js';
 import { getSessionBaseDir, getSessionName } from '../session/paths.js';
@@ -370,6 +371,17 @@ export function unknownHelpTopicError(topic, closest) {
             : `Run "bdg ${parent ? `${parent} ` : ''}--help" for commands`,
     };
 }
+/**
+ * "Did you mean" for one or more close candidates, joined as a sentence.
+ *
+ * @param candidates - Close matches, e.g. ["form", "frames"]
+ * @returns e.g. "Did you mean: form or frames?" or "Did you mean: a, b or c?"
+ */
+export function didYouMeanSuggestion(candidates) {
+    const last = candidates.at(-1) ?? '';
+    const rest = candidates.slice(0, -1);
+    return `Did you mean: ${rest.length > 0 ? `${rest.join(', ')} or ${last}` : last}?`;
+}
 /**
  * Suggestion for a command-line usage error (missing argument, invalid value,
  * unknown option without a close match).
@@ -498,7 +510,7 @@ export function invalidSessionNameError(name, maxLength) {
 export function sessionNameSocketTooLongError(name, socketPath, max) {
     return {
         message: `Session name "${name}" makes the daemon socket path too long (${Buffer.byteLength(socketPath)} bytes, at most ${max}): ${socketPath}`,
-        suggestion: 'Use a shorter session name, or a shorter BDG_SESSION_DIR (e.g. /tmp/bdg)',
+        suggestion: `Use a shorter session name, or a shorter BDG_SESSION_DIR (e.g. ${privateSessionDirExample()})`,
     };
 }
 /**
@@ -524,15 +536,36 @@ export function purgeRefusedError(dir, reason) {
         suggestion: `End the session first (${sessionCommand('bdg cleanup --force')}), then retry: ${sessionCommand('bdg cleanup --purge')}`,
     };
 }
-/** Fix for an unusable session directory */
-const SESSION_DIR_SUGGESTION = 'Set BDG_SESSION_DIR to a short, writable directory, e.g. BDG_SESSION_DIR=/tmp/bdg';
+/**
+ * A short session directory only the user can use, for suggestions: in
+ * `$XDG_RUNTIME_DIR` (Linux, private to the user) when set, else a per-user
+ * name in the OS temp directory (per-user on macOS). Never the shared
+ * `/tmp/bdg`, which another user can create first.
+ *
+ * @returns Absolute directory path
+ */
+function privateSessionDirExample() {
+    const runtimeDir = process.env['XDG_RUNTIME_DIR']?.trim();
+    if (runtimeDir)
+        return path.join(runtimeDir, 'bdg');
+    const uid = process.getuid?.();
+    return path.join(os.tmpdir(), uid === undefined ? 'bdg' : `bdg-${uid}`);
+}
+/**
+ * Fix for an unusable session directory.
+ *
+ * @returns Suggestion naming a private, short directory
+ */
+function sessionDirSuggestion() {
+    return `Set BDG_SESSION_DIR to a short directory only you can write to, e.g. BDG_SESSION_DIR=${privateSessionDirExample()}`;
+}
 /**
  * The session directory exists but is not a directory.
  *
  * @param dir - Session directory
  */
 export function sessionDirIsFileError(dir) {
-    return { message: `Session directory ${dir} is a file`, suggestion: SESSION_DIR_SUGGESTION };
+    return { message: `Session directory ${dir} is a file`, suggestion: sessionDirSuggestion() };
 }
 /**
  * The session directory cannot be created or written.
@@ -543,7 +576,54 @@ export function sessionDirIsFileError(dir) {
 export function sessionDirNotWritableError(dir, reason) {
     return {
         message: `Session directory ${dir} is not writable (${reason})`,
-        suggestion: SESSION_DIR_SUGGESTION,
+        suggestion: sessionDirSuggestion(),
+    };
+}
+/**
+ * The session directory, or one above it, is not safe to use: another user
+ * could replace the daemon socket or plant files there.
+ *
+ * @param untrusted - Untrusted directory and why
+ */
+export function untrustedSessionDirError(untrusted) {
+    return {
+        message: `Session directory ${untrusted.dir} is not safe to use: ${untrusted.reason}`,
+        suggestion: untrustedSessionDirSuggestion(untrusted),
+    };
+}
+/**
+ * Fix for an untrusted session directory: remove a symlink, use a
+ * subdirectory of a shared sticky directory (`BDG_SESSION_DIR=/tmp`), chmod
+ * a directory bdg owns (`~/.bdg`, `sessions/`, `sessions/<name>`), else
+ * choose another `BDG_SESSION_DIR`.
+ *
+ * @param untrusted - Untrusted directory and why
+ * @returns Suggestion
+ */
+function untrustedSessionDirSuggestion(untrusted) {
+    const { dir, kind, bdgOwned } = untrusted;
+    const example = `BDG_SESSION_DIR=${privateSessionDirExample()}`;
+    if (kind === 'symlink') {
+        return `Remove the link (rm ${dir}) or point BDG_SESSION_DIR at the real directory`;
+    }
+    if (kind === 'shared') {
+        return `${dir} is shared by all users; use a subdirectory only you can write to, e.g. ${example}`;
+    }
+    if (bdgOwned)
+        return `Run chmod 700 ${dir} (or remove it if it is not yours), then retry`;
+    return `Use a directory you own that others cannot write to, e.g. ${example} (or chmod 700 ${dir} if it is yours)`;
+}
+/**
+ * The daemon log cannot be opened for writing (a symlink there is refused,
+ * not followed).
+ *
+ * @param logPath - Daemon log path
+ * @param code - File-system error code
+ */
+export function daemonLogNotOpenedError(logPath, code) {
+    return {
+        message: `Cannot open the daemon log ${logPath} (${code === 'ELOOP' ? 'it is a symbolic link' : code})`,
+        suggestion: `Remove ${logPath} if you did not create it, then retry`,
     };
 }
 /**
@@ -555,7 +635,7 @@ export function sessionDirNotWritableError(dir, reason) {
 export function socketPathTooLongError(socketPath, max) {
     return {
         message: `Session directory path is too long for the daemon socket (${Buffer.byteLength(socketPath)} bytes, at most ${max}): ${socketPath}`,
-        suggestion: SESSION_DIR_SUGGESTION,
+        suggestion: sessionDirSuggestion(),
     };
 }
 /**