browser-debugger-cli 0.7.2 → 0.9.0

package/dist/session/QueryCacheManager.js

@@ -1,22 +1,17 @@
 /**
  * Query cache manager for DOM element index-based access.
  *
- * Provides centralized management of DOM query result caching with:
- * - Singleton pattern for consistent cache access
- * - Navigation-aware staleness detection
- * - TTL-based navigation ID caching to reduce IPC calls
- *
- * The cache enables index-based element access patterns like
- * "bdg dom get 0" after running "bdg dom query .selector".
+ * Stores the last `bdg dom query` / `bdg dom form` result so later commands
+ * can address its elements by index ("bdg dom get 0"). Each cached node holds
+ * its backend node id, which identifies that exact element for as long as it
+ * stays in the page; whether it still does is checked when the index is used,
+ * not here.
  *
  * @example
  * ```typescript
  * const manager = QueryCacheManager.getInstance();
- *
- * // Store query results
  * await manager.set(queryResult);
  *
- * // Validate and retrieve (throws if stale)
  * const validation = await manager.validate();
  * if (validation.valid) {
  *   const cache = validation.cache;
@@ -26,22 +21,46 @@
 import { existsSync } from 'fs';
 import { readFile, rm, writeFile } from 'fs/promises';
 import { join } from 'path';
-import { getSessionDir } from '../session/paths.js';
+import { getSessionDir } from './paths.js';
 import { createLogger } from '../ui/logging/index.js';
+import { sessionCommand } from '../ui/messages/sessionCommand.js';
 import { getErrorMessage } from '../utils/errors.js';
 const log = createLogger('session');
-/** TTL for cached navigation ID (500ms). */
-const NAVIGATION_ID_CACHE_TTL_MS = 500;
 /**
- * Singleton manager for DOM query result caching.
+ * Cache format version. Version 2 stores backend node ids; older caches held
+ * per-connection node ids that are meaningless to later commands.
+ */
+const CACHE_VERSION = 2;
+/**
+ * Selector recorded for `dom form` results (fields carry their own selectors).
+ */
+export const FORM_DISCOVERY_CACHE_SELECTOR = 'form:auto-discovered';
+/** Prefix of the selector recorded for `dom a11y query` results (followed by the pattern) */
+export const A11Y_CACHE_SELECTOR_PREFIX = 'a11y ';
+/**
+ * The list an index refers to, from the selector recorded with the cache.
  *
- * Centralizes all cache operations with navigation-aware staleness detection.
- * Uses file-based persistence for cross-process access.
+ * @param index - The index the user gave
+ * @param cacheSelector - Selector recorded with the cached results
+ * @returns The command whose results are cached, and its query
+ */
+export function indexSourceOf(index, cacheSelector) {
+    if (cacheSelector === FORM_DISCOVERY_CACHE_SELECTOR)
+        return { index, command: 'dom form' };
+    if (cacheSelector.startsWith(A11Y_CACHE_SELECTOR_PREFIX)) {
+        return {
+            index,
+            command: 'dom a11y query',
+            query: cacheSelector.slice(A11Y_CACHE_SELECTOR_PREFIX.length),
+        };
+    }
+    return { index, command: 'dom query', query: cacheSelector };
+}
+/**
+ * Singleton manager for the on-disk query cache.
  */
 export class QueryCacheManager {
     static instance = null;
-    /** Cached navigation ID with timestamp for TTL-based invalidation. */
-    cachedNavigationId = null;
     /**
      * Get the singleton instance.
      *
@@ -58,24 +77,22 @@ export class QueryCacheManager {
         QueryCacheManager.instance = null;
     }
     /**
-     * Get path to query cache file.
+     * Path of the cache file in the session directory.
      *
-     * @returns Absolute path to query-cache.json
+     * @returns Absolute cache file path
      */
     getCachePath() {
         return join(getSessionDir(), 'query-cache.json');
     }
     /**
-     * Store query results for index-based access.
+     * Store a query result.
      *
-     * Writes results to ~/.bdg/query-cache.json for cross-process access.
-     *
-     * @param result - DOM query result to cache
+     * @param result - Query result whose nodes carry backend node ids
      */
     async set(result) {
         try {
             const cachePath = this.getCachePath();
-            await writeFile(cachePath, JSON.stringify(result), 'utf-8');
+            await writeFile(cachePath, JSON.stringify({ version: CACHE_VERSION, ...result }), 'utf-8');
             log.debug(`Cached ${result.nodes.length} query results to ${cachePath}`);
         }
         catch (error) {
@@ -83,92 +100,35 @@ export class QueryCacheManager {
         }
     }
     /**
-     * Get validated cache results.
-     *
-     * Returns null if cache is stale or doesn't exist.
-     * Use getRaw() for unchecked access.
-     *
-     * @returns Cached query result or null if invalid/missing
-     */
-    async get() {
-        const validation = await this.validate();
-        return validation.valid ? validation.cache : null;
-    }
-    /**
-     * Get raw cache without validation.
-     *
-     * Reads from ~/.bdg/query-cache.json if it exists.
-     * Does not check navigation staleness.
+     * Read the cache and check that it can be used.
      *
-     * @returns Cached query result or null if no cache exists
-     */
-    async getRaw() {
-        try {
-            const cachePath = this.getCachePath();
-            if (!existsSync(cachePath)) {
-                return null;
-            }
-            const content = await readFile(cachePath, 'utf-8');
-            const result = JSON.parse(content);
-            log.debug(`Retrieved ${result.nodes.length} cached query results`);
-            return result;
-        }
-        catch (error) {
-            log.debug(`Failed to read query cache: ${getErrorMessage(error)}`);
-            return null;
-        }
-    }
-    /**
-     * Validate cache against current navigation state.
-     *
-     * Checks if the cached query results are still valid by comparing
-     * the stored navigationId with the current one from the daemon.
-     *
-     * @returns Validation result with cache and error info
-     *
-     * @example
-     * ```typescript
-     * const validation = await manager.validate();
-     * if (!validation.valid) {
-     *   throw new CommandError(validation.error, { suggestion: validation.suggestion });
-     * }
-     * const cache = validation.cache;
-     * ```
+     * @returns Validation result with the cached query when usable
      */
     async validate() {
-        const cache = await this.getRaw();
-        if (!cache) {
+        const raw = await this.read();
+        if (!raw) {
             return {
                 valid: false,
                 cache: null,
                 error: 'No cached query results found',
-                suggestion: 'Run "bdg dom query <selector>" first to generate indexed results',
+                suggestion: `Run "${sessionCommand('bdg dom query <selector>')}" first to generate indexed results`,
             };
         }
-        if (cache.navigationId === undefined) {
-            log.debug('Query cache missing navigationId (legacy format), allowing access');
-            return { valid: true, cache };
-        }
-        const currentNavId = await this.getCurrentNavigationId();
-        if (currentNavId === null) {
-            log.debug('Could not get current navigationId, allowing cache access');
-            return { valid: true, cache };
-        }
-        if (cache.navigationId !== currentNavId) {
+        const { version, ...cache } = raw;
+        if (version !== CACHE_VERSION) {
             return {
                 valid: false,
-                cache,
-                error: `Query cache is stale (page has navigated since query was run)`,
-                suggestion: `Re-run "bdg dom query ${cache.selector}" to refresh cached results`,
+                cache: null,
+                error: 'Cached query results are from an older bdg version',
+                suggestion: cache.selector === FORM_DISCOVERY_CACHE_SELECTOR
+                    ? `Re-run "${sessionCommand('bdg dom form')}" to refresh cached results`
+                    : `Re-run "${sessionCommand(`bdg dom query ${cache.selector}`)}" to refresh cached results`,
             };
         }
         return { valid: true, cache };
     }
     /**
-     * Clear the query cache.
-     *
-     * Removes ~/.bdg/query-cache.json.
-     * Called when starting a new query or when the session ends.
+     * Remove the cache file.
      */
     async clear() {
         try {
@@ -183,51 +143,21 @@ export class QueryCacheManager {
         }
     }
     /**
-     * Check if cache file exists.
+     * Read the raw cache file.
      *
-     * @returns True if cache file exists
+     * @returns Parsed cache content, or null if missing/unreadable
      */
-    exists() {
-        return existsSync(this.getCachePath());
-    }
-    /**
-     * Get current navigation ID from the daemon.
-     *
-     * Caches the result for 500ms to avoid redundant IPC calls within a single
-     * command execution while ensuring freshness for subsequent commands.
-     *
-     * @returns Current navigation ID or null if unavailable
-     */
-    async getCurrentNavigationId() {
-        if (this.cachedNavigationId &&
-            Date.now() - this.cachedNavigationId.timestamp < NAVIGATION_ID_CACHE_TTL_MS) {
-            return this.cachedNavigationId.value;
-        }
+    async read() {
         try {
-            const { getStatus } = await import('../ipc/client.js');
-            const response = await getStatus();
-            if (response.status === 'ok' && response.data?.navigationId !== undefined) {
-                this.cachedNavigationId = {
-                    value: response.data.navigationId,
-                    timestamp: Date.now(),
-                };
-                return response.data.navigationId;
-            }
-            return null;
+            const cachePath = this.getCachePath();
+            if (!existsSync(cachePath))
+                return null;
+            return JSON.parse(await readFile(cachePath, 'utf-8'));
         }
         catch (error) {
-            log.debug(`Failed to get current navigation ID: ${getErrorMessage(error)}`);
+            log.debug(`Failed to read query cache: ${getErrorMessage(error)}`);
             return null;
         }
     }
-    /**
-     * Invalidate cached navigation ID.
-     *
-     * Forces fresh fetch on next getCurrentNavigationId() call.
-     * Useful after navigation events.
-     */
-    invalidateNavigationCache() {
-        this.cachedNavigationId = null;
-    }
 }
 //# sourceMappingURL=QueryCacheManager.js.map

package/dist/session/chrome.d.ts

@@ -43,24 +43,29 @@ export declare function readChromePid(): number | null;
  * Safe to call multiple times (idempotent).
  */
 export declare function clearChromePid(): void;
+/** What `status --verbose` shows about the session's Chrome */
+export interface RunningChromeInfo {
+    /** Executable the process was started from */
+    executable: string;
+    /** Whether it runs without a window */
+    headless: boolean;
+    /** Profile directory, when given on its command line */
+    userDataDir?: string;
+}
 /**
- * Aggressively cleanup stale Chrome processes launched by bdg.
+ * Describe a running Chrome from its command line (fast, unlike scanning the
+ * system for installations).
  *
- * Kills Chrome instances that were launched by bdg by:
- * 1. Reading the Chrome PID from persistent cache
- * 2. Killing that specific Chrome process using cross-platform kill logic
- *
- * The cache survives session cleanup, so this works even after a normal session end.
- *
- * Cross-platform killing:
- * - Windows: Uses `taskkill /pid <pid> /T /F` to kill process tree
- * - Unix/macOS: Uses `process.kill(-pid, 'SIGKILL')` to kill process group
- *
- * Note: We can't use chromeLauncher.killAll() because it only tracks instances
- * created via chromeLauncher.launch(), but we use new chromeLauncher.Launcher()
- * which doesn't register in that tracking set.
+ * @param pid - Chrome process ID
+ * @returns Executable, mode and profile, or null if the process is gone
+ */
+export declare function describeRunningChrome(pid: number): RunningChromeInfo | null;
+/**
+ * Executable, mode and profile from a Chrome command line. Paths may contain
+ * spaces: a value runs until the next ` --`.
  *
- * @returns Number of errors encountered during cleanup
+ * @param command - Full command line
+ * @returns Chrome info
  */
-export declare function cleanupStaleChrome(): Promise<number>;
+export declare function parseChromeCommand(command: string): RunningChromeInfo;
 //# sourceMappingURL=chrome.d.ts.map

package/dist/session/chrome.js

@@ -8,7 +8,7 @@ import * as fs from 'fs';
 import { createLogger } from '../ui/logging/index.js';
 import { AtomicFileWriter } from '../utils/atomicFile.js';
 import { getErrorMessage } from '../utils/errors.js';
-import { isProcessAlive } from '../utils/process.js';
+import { getProcessCommand, isProcessAlive } from '../utils/process.js';
 import { getSessionFilePath, ensureSessionDir } from './paths.js';
 const log = createLogger('chrome');
 /**
@@ -18,8 +18,11 @@ const log = createLogger('chrome');
  * @returns Parsed PID or null if invalid
  */
 function parseChromePid(pidStr) {
-    const pid = parseInt(pidStr.trim(), 10);
-    return Number.isNaN(pid) ? null : pid;
+    const trimmed = pidStr.trim();
+    if (!/^\d+$/.test(trimmed))
+        return null;
+    const pid = Number(trimmed);
+    return pid > 0 ? pid : null;
 }
 /**
  * Remove Chrome PID cache file safely.
@@ -108,49 +111,30 @@ export function clearChromePid() {
     }
 }
 /**
- * Aggressively cleanup stale Chrome processes launched by bdg.
- *
- * Kills Chrome instances that were launched by bdg by:
- * 1. Reading the Chrome PID from persistent cache
- * 2. Killing that specific Chrome process using cross-platform kill logic
- *
- * The cache survives session cleanup, so this works even after a normal session end.
- *
- * Cross-platform killing:
- * - Windows: Uses `taskkill /pid <pid> /T /F` to kill process tree
- * - Unix/macOS: Uses `process.kill(-pid, 'SIGKILL')` to kill process group
+ * Describe a running Chrome from its command line (fast, unlike scanning the
+ * system for installations).
  *
- * Note: We can't use chromeLauncher.killAll() because it only tracks instances
- * created via chromeLauncher.launch(), but we use new chromeLauncher.Launcher()
- * which doesn't register in that tracking set.
+ * @param pid - Chrome process ID
+ * @returns Executable, mode and profile, or null if the process is gone
+ */
+export function describeRunningChrome(pid) {
+    const command = getProcessCommand(pid);
+    return command ? parseChromeCommand(command) : null;
+}
+/**
+ * Executable, mode and profile from a Chrome command line. Paths may contain
+ * spaces: a value runs until the next ` --`.
  *
- * @returns Number of errors encountered during cleanup
+ * @param command - Full command line
+ * @returns Chrome info
  */
-export async function cleanupStaleChrome() {
-    const { cleanupChromeAttemptingMessage, cleanupChromePidNotFoundMessage, cleanupChromeKillingMessage, cleanupChromeSuccessMessage, cleanupChromeFailedMessage, cleanupChromeProcessFailedMessage, } = await import('../ui/messages/chrome.js');
-    console.error(cleanupChromeAttemptingMessage());
-    try {
-        const { killChromeProcess } = await import('../utils/process.js');
-        const chromePid = readChromePid();
-        if (!chromePid) {
-            console.error(cleanupChromePidNotFoundMessage());
-            return 0;
-        }
-        console.error(cleanupChromeKillingMessage(chromePid));
-        try {
-            killChromeProcess(chromePid, 'SIGKILL');
-            console.error(cleanupChromeSuccessMessage());
-            clearChromePid();
-            return 0;
-        }
-        catch (killError) {
-            console.error(cleanupChromeFailedMessage(getErrorMessage(killError)));
-            return 1;
-        }
-    }
-    catch (error) {
-        console.error(cleanupChromeProcessFailedMessage(getErrorMessage(error)));
-        return 1;
-    }
+export function parseChromeCommand(command) {
+    const flagsStart = command.indexOf(' --');
+    const userDataDir = /--user-data-dir=(.+?)(?= --|$)/.exec(command)?.[1];
+    return {
+        executable: flagsStart === -1 ? command : command.slice(0, flagsStart),
+        headless: /(^| )--headless\b/.test(command),
+        ...(userDataDir !== undefined && { userDataDir }),
+    };
 }
 //# sourceMappingURL=chrome.js.map

package/dist/session/chromeOwners.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Which other bdg session uses a Chrome, so `--chrome-ws-url` never takes over
+ * a tab another session drives, nor a Chrome another session launched (and
+ * closes when it stops).
+ *
+ * Sessions are found in this base directory and, through the machine-wide
+ * port registry, in other base directories whose sessions claimed a port.
+ */
+/**
+ * A running session and the Chrome tab it drives.
+ */
+export interface ChromeOwner {
+    /** Session name, or null for a default session */
+    name: string | null;
+    /** Session directory */
+    dir: string;
+    /** Base directory of the session (its `BDG_SESSION_DIR`) */
+    baseDir: string;
+    /** Target (tab) the session drives */
+    targetId: string;
+    /** Whether the session launched that Chrome (it closes Chrome when it stops) */
+    launched: boolean;
+}
+/**
+ * Another running session that a new session attaching to a Chrome would
+ * collide with: one that launched that Chrome, or one driving the tab the
+ * new session would use.
+ *
+ * @param chromeTargetIds - Ids of every target of the Chrome being attached to
+ * @param targetId - Tab the new session would drive
+ * @returns The conflicting session, or null
+ */
+export declare function findConflictingOwner(chromeTargetIds: readonly string[], targetId: string): Promise<ChromeOwner | null>;
+//# sourceMappingURL=chromeOwners.d.ts.map

package/dist/session/chromeOwners.js

@@ -0,0 +1,51 @@
+/**
+ * Which other bdg session uses a Chrome, so `--chrome-ws-url` never takes over
+ * a tab another session drives, nor a Chrome another session launched (and
+ * closes when it stops).
+ *
+ * Sessions are found in this base directory and, through the machine-wide
+ * port registry, in other base directories whose sessions claimed a port.
+ */
+import * as fs from 'fs';
+import { probeDaemonSocket } from './daemonSocket.js';
+import { sessionFilePathIn, sessionOfDir } from './paths.js';
+import { otherSessionDirs } from './portClaims.js';
+import { createLogger, logDebugError } from '../ui/logging/index.js';
+const log = createLogger('session');
+/**
+ * The tab a running session drives, from its metadata.
+ *
+ * @param dir - Session directory
+ * @returns Owner info, or null without a running session or metadata
+ */
+async function readOwner(dir) {
+    if ((await probeDaemonSocket(sessionFilePathIn(dir, 'DAEMON_SOCKET'))) !== 'alive')
+        return null;
+    try {
+        const meta = JSON.parse(fs.readFileSync(sessionFilePathIn(dir, 'METADATA'), 'utf8'));
+        if (typeof meta.targetId !== 'string')
+            return null;
+        const launched = typeof meta.chromePid === 'number' && meta.chromePid > 0;
+        return { ...sessionOfDir(dir), dir, targetId: meta.targetId, launched };
+    }
+    catch (error) {
+        logDebugError(log, `read the metadata in ${dir}`, error);
+        return null;
+    }
+}
+/**
+ * Another running session that a new session attaching to a Chrome would
+ * collide with: one that launched that Chrome, or one driving the tab the
+ * new session would use.
+ *
+ * @param chromeTargetIds - Ids of every target of the Chrome being attached to
+ * @param targetId - Tab the new session would drive
+ * @returns The conflicting session, or null
+ */
+export async function findConflictingOwner(chromeTargetIds, targetId) {
+    const owners = await Promise.all(otherSessionDirs().map(readOwner));
+    return (owners.find((owner) => owner !== null &&
+        chromeTargetIds.includes(owner.targetId) &&
+        (owner.launched || owner.targetId === targetId)) ?? null);
+}
+//# sourceMappingURL=chromeOwners.js.map

package/dist/session/cleanup/staleSession.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Cleanup of state left behind by a daemon that died without tearing down.
+ *
+ * A healthy daemon removes its own files on exit. These helpers only matter
+ * after a crash or SIGKILL. Processes are signalled only after their command
+ * line confirms they are what the PID file claims, so a reused PID can never
+ * get an unrelated process killed.
+ */
+/**
+ * Remove per-session files (metadata, query cache).
+ *
+ * Called by the daemon when its session ends, and by `bdg cleanup`.
+ */
+export declare function removeSessionFiles(): void;
+/**
+ * Remove daemon and session files if no daemon is listening.
+ *
+ * @returns True if a stale daemon socket was found and cleaned up
+ */
+export declare function removeStaleDaemonFiles(): Promise<boolean>;
+/**
+ * The Chrome recorded in chrome.pid, if it is still running and still the
+ * Chrome bdg launched for this session directory (verified by its marker
+ * flag). A PID that now belongs to another process is dropped.
+ *
+ * @returns Chrome PID, or null
+ */
+export declare function findOrphanedChrome(): number | null;
+/**
+ * Whether a process is the Chrome bdg launched for a session directory: its
+ * command line carries the directory's marker flag.
+ *
+ * @param pid - Process ID
+ * @param sessionDir - Session directory
+ * @returns True for that session's Chrome
+ */
+export declare function isSessionChrome(pid: number, sessionDir: string): boolean;
+/**
+ * Kill the Chrome recorded in chrome.pid, if it is still the Chrome bdg launched
+ * for this session directory (verified by its marker flag).
+ *
+ * @returns True if a Chrome process was killed
+ */
+export declare function killOrphanedChrome(): boolean;
+/**
+ * Kill an orphaned Chrome (see {@link killOrphanedChrome}) and wait until it
+ * has exited, so its debugging port is free for the next launch.
+ *
+ * @returns True if a Chrome process was killed
+ */
+export declare function reapOrphanedChrome(): Promise<boolean>;
+/**
+ * Read the PID of a live bdg daemon from daemon.pid.
+ *
+ * @param dir - Session directory (defaults to the selected session's)
+ * @returns Daemon PID if the process is alive and is a bdg daemon, else null
+ */
+export declare function readLiveDaemonPid(dir?: string): number | null;
+//# sourceMappingURL=staleSession.d.ts.map