browser-debugger-cli 0.7.1 → 0.8.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,24 @@
 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 { 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.
- *
- * Centralizes all cache operations with navigation-aware staleness detection.
- * Uses file-based persistence for cross-process access.
+ * 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';
+/**
+ * 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 +55,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.
-     *
-     * Writes results to ~/.bdg/query-cache.json for cross-process access.
+     * Store a query result.
      *
-     * @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,61 +78,13 @@ 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.
-     *
-     * @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.
+     * Read the cache and check that it can be used.
      *
-     * 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,
@@ -145,30 +92,21 @@ export class QueryCacheManager {
                 suggestion: 'Run "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 "bdg dom form" to refresh cached results'
+                    : `Re-run "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 +121,21 @@ export class QueryCacheManager {
         }
     }
     /**
-     * Check if cache file exists.
-     *
-     * @returns True if cache file exists
-     */
-    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.
+     * Read the raw cache file.
      *
-     * @returns Current navigation ID or null if unavailable
+     * @returns Parsed cache content, or null if missing/unreadable
      */
-    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/cleanup/staleSession.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 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;
+/**
+ * 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.
+ *
+ * @returns Daemon PID if the process is alive and is a bdg daemon, else null
+ */
+export declare function readLiveDaemonPid(): number | null;
+//# sourceMappingURL=staleSession.d.ts.map

package/dist/session/cleanup/staleSession.js

@@ -0,0 +1,124 @@
+/**
+ * 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.
+ */
+import { chromeSessionMarkerFlag } from '../../connection/launcher/flagsBuilder.js';
+import { QueryCacheManager } from '../QueryCacheManager.js';
+import { clearChromePid, readChromePid } from '../chrome.js';
+import { probeDaemonSocket } from '../daemonSocket.js';
+import { getSessionDir, getSessionFilePath } from '../paths.js';
+import { readDaemonPid } from '../pid.js';
+import { createLogger, logDebugError } from '../../ui/logging/index.js';
+import { delay } from '../../utils/async.js';
+import { safeRemoveFile } from '../../utils/file.js';
+import { DAEMON_SCRIPT_PATH } from '../../utils/packageRoot.js';
+import { getProcessCommand, isProcessAlive, killChromeProcess } from '../../utils/process.js';
+const log = createLogger('cleanup');
+/**
+ * Check whether a process command line contains an exact argument.
+ *
+ * @param command - Full command line
+ * @param arg - Argument to look for
+ * @returns True if `arg` appears as a whole space-delimited argument
+ */
+function hasArgument(command, arg) {
+    if (!command)
+        return false;
+    return command.includes(`${arg} `) || command.endsWith(arg);
+}
+/**
+ * Remove per-session files (metadata, query cache).
+ *
+ * Called by the daemon when its session ends, and by `bdg cleanup`.
+ */
+export function removeSessionFiles() {
+    safeRemoveFile(getSessionFilePath('METADATA'), 'metadata file', log);
+    void QueryCacheManager.getInstance()
+        .clear()
+        .catch((error) => logDebugError(log, 'clear query cache', error));
+}
+/**
+ * Remove daemon and session files if no daemon is listening.
+ *
+ * @returns True if a stale daemon socket was found and cleaned up
+ */
+export async function removeStaleDaemonFiles() {
+    const probe = await probeDaemonSocket();
+    if (probe === 'alive')
+        return false;
+    safeRemoveFile(getSessionFilePath('DAEMON_SOCKET'), 'daemon socket', log);
+    safeRemoveFile(getSessionFilePath('DAEMON_PID'), 'daemon PID file', log);
+    removeSessionFiles();
+    return probe === 'stale';
+}
+/**
+ * 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 function findOrphanedChrome() {
+    const chromePid = readChromePid();
+    if (!chromePid)
+        return null;
+    if (hasArgument(getProcessCommand(chromePid), chromeSessionMarkerFlag(getSessionDir()))) {
+        return chromePid;
+    }
+    log.debug(`PID ${chromePid} is no longer a bdg Chrome; dropping chrome.pid`);
+    clearChromePid();
+    return null;
+}
+/**
+ * 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 function killOrphanedChrome() {
+    const chromePid = findOrphanedChrome();
+    if (!chromePid)
+        return false;
+    log.info(`Killing orphaned Chrome (PID ${chromePid})`);
+    try {
+        killChromeProcess(chromePid, 'SIGKILL');
+    }
+    catch (error) {
+        logDebugError(log, `kill Chrome ${chromePid}`, error);
+    }
+    clearChromePid();
+    return true;
+}
+/** How long to wait for a killed orphaned Chrome to exit (and free its port) */
+const ORPHAN_EXIT_WAIT_MS = 5000;
+/**
+ * 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 async function reapOrphanedChrome() {
+    const chromePid = findOrphanedChrome();
+    if (!killOrphanedChrome() || chromePid === null)
+        return false;
+    const deadline = Date.now() + ORPHAN_EXIT_WAIT_MS;
+    while (isProcessAlive(chromePid) && Date.now() < deadline)
+        await delay(50);
+    return true;
+}
+/**
+ * Read the PID of a live bdg daemon from daemon.pid.
+ *
+ * @returns Daemon PID if the process is alive and is a bdg daemon, else null
+ */
+export function readLiveDaemonPid() {
+    const pid = readDaemonPid();
+    if (!pid || !isProcessAlive(pid))
+        return null;
+    return hasArgument(getProcessCommand(pid), DAEMON_SCRIPT_PATH) ? pid : null;
+}
+//# sourceMappingURL=staleSession.js.map

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

@@ -0,0 +1,36 @@
+/**
+ * Cleanup behind the user-facing `bdg cleanup` command.
+ */
+/**
+ * Options for session cleanup.
+ */
+export interface SessionCleanupOptions {
+    /** Kill a running (possibly hung) daemon before cleaning */
+    force?: boolean | undefined;
+    /** Also remove the legacy session.json output file */
+    removeOutput?: boolean | undefined;
+}
+/**
+ * Result of session cleanup.
+ */
+export interface SessionCleanupResult {
+    cleaned: {
+        session: boolean;
+        chrome: boolean;
+        daemons: boolean;
+        output: boolean;
+    };
+    warnings: string[];
+}
+/**
+ * Clean up session state.
+ *
+ * With `force`, a live daemon is killed first (after verifying its command
+ * line). Then stale daemon files are removed and an orphaned bdg Chrome, if
+ * any, is killed.
+ *
+ * @param options - Cleanup options
+ * @returns What was cleaned, plus warnings
+ */
+export declare function performSessionCleanup(options: SessionCleanupOptions): Promise<SessionCleanupResult>;
+//# sourceMappingURL=userCommands.d.ts.map