browser-debugger-cli 0.7.2 → 0.9.0

package/README.md

@@ -9,7 +9,7 @@ Chrome DevTools Protocol in your terminal. Opens a persistent connection to Chro
 
 ## Why bdg?
 
-- **Raw CDP access** - All [644 protocol methods](https://chromedevtools.github.io/devtools-protocol/) available directly
+- **Raw CDP access** - Every [protocol method](https://chromedevtools.github.io/devtools-protocol/) available directly
 - **Token efficient** - No overhead from MCP tool definitions; progressive discovery loads only what's needed
 - **Self-correcting** - Errors clearly exposed with semantic exit codes and suggestions
 - **Composable** - Unix philosophy: pipes, jq, shell scripts work naturally
@@ -33,9 +33,11 @@ We benchmarked bdg against Chrome DevTools MCP Server on real developer debuggin
 ## Install
 
 ```bash
-npm install -g browser-debugger-cli@alpha
+npm install -g browser-debugger-cli
 ```
 
+**Requirements:** Node.js 22.12+ and Chrome (or Chromium).
+
 **Platform Support:**
 - ✅ macOS and Linux
 - ✅ Windows via WSL
@@ -50,25 +52,34 @@ bdg https://localhost:5173 --chrome-flags="--disable-web-security"       # Disab
 bdg cdp --search cookie            # Discover commands
 bdg cdp Network.getCookies         # Run any CDP method
 bdg dom query "button"             # High-level helpers
+bdg dom fill 'input[name="q"]' "shoes"
+bdg dom click 'button:has-text("Search")'
+bdg page navigate example.com/about
+bdg eval "document.title"          # Run JavaScript in the page (--frame for iframes)
+bdg network list --preset errors   # Network requests, console: bdg console
+bdg dom listeners "#save"          # Which event listeners run for an element
+bdg dom layout "#save"             # Where it is, whether it is visible or covered
+bdg dom wait "#result" --visible   # Wait for an element instead of sleeping
+bdg example.com --session agent2 --viewport 1280x800   # A second, independent session
 bdg stop                           # End session
 ```
 
 ## Current State
 
-**Raw CDP access is complete.** All 644 protocol methods (53 domains) work now. High-level wrappers (`bdg dom`, `bdg network`) are being added for common operations. See [Commands](https://github.com/szymdzum/browser-debugger-cli/wiki/Commands) for full reference.
+**Raw CDP access is complete.** Every protocol method works now. High-level commands cover the common work: page navigation, DOM queries and interaction (click, fill, hover, keys, forms, shadow DOM and iframes), accessibility tree, screenshots, network requests and HAR export, console messages and event listeners. Actions report what they changed (navigation, new messages, requests, or no visible effect), and several named sessions can run side by side. See the [CLI reference](docs/CLI_REFERENCE.md) for every command, and `bdg --help --json` for the machine-readable version.
 
 ## Agent Discovery Pattern
 
 ```bash
 # Agent explores what's possible (no docs needed)
-bdg cdp --list                              # 53 domains
-bdg cdp Network --list                      # 39 methods
+bdg cdp --list                              # All domains
+bdg cdp Network --list                      # Methods in one domain
 bdg cdp Network.getCookies --describe       # Full schema + examples
 bdg cdp Network.getCookies                  # Execute
 
 # Search across all domains
 bdg cdp --search screenshot                 # Find relevant methods
-bdg cdp --search cookie                     # 14 results
+bdg cdp --search cookie                     # methods mentioning cookies
 ```
 
 ## Documentation

package/dist/cdp/protocol.d.ts

@@ -20,7 +20,7 @@ import type { ProtocolSchema, Domain, Command } from './types.js';
  * ```typescript
  * const protocol = loadProtocol();
  * console.log(`Protocol version: ${protocol.version.major}.${protocol.version.minor}`);
- * console.log(`Domains: ${protocol.domains.length}`); // ~53 domains (47 browser + 6 JS)
+ * console.log(`Domains: ${protocol.domains.length}`); // browser + JS domains
  * ```
  */
 export declare function loadProtocol(): ProtocolSchema;

package/dist/cdp/protocol.js

@@ -24,7 +24,7 @@ let cachedProtocol = null;
  * ```typescript
  * const protocol = loadProtocol();
  * console.log(`Protocol version: ${protocol.version.major}.${protocol.version.minor}`);
- * console.log(`Domains: ${protocol.domains.length}`); // ~53 domains (47 browser + 6 JS)
+ * console.log(`Domains: ${protocol.domains.length}`); // browser + JS domains
  * ```
  */
 export function loadProtocol() {

package/dist/cdp/schema.d.ts

@@ -141,10 +141,22 @@ export declare function getDomainSummary(domainName: string): DomainSummary | un
  * ```
  */
 export declare function getAllDomainSummaries(): DomainSummary[];
+/**
+ * Domain and method counts of the bundled protocol (for help text).
+ *
+ * @returns Number of domains, of methods overall, and of methods per domain
+ */
+export declare function getProtocolCounts(): {
+    domains: number;
+    methods: number;
+    methodsIn: (domain: string) => number;
+};
 /**
  * Search methods by keyword (case-insensitive).
  *
- * Searches in method names and descriptions.
+ * Searches method names, extra keywords ({@link SEARCH_KEYWORDS}) and
+ * descriptions. Matches by name or keyword come first, then those found only
+ * in the description, each in protocol order.
  *
  * @param query - Search query
  * @returns Array of matching method schemas
@@ -153,6 +165,7 @@ export declare function getAllDomainSummaries(): DomainSummary[];
  * ```typescript
  * const cookies = searchMethods('cookie');
  * // Returns: Network.getCookies, Network.setCookie, Network.deleteCookies, etc.
+ * searchMethods('viewport')[0]?.name; // 'Emulation.setDeviceMetricsOverride'
  * ```
  */
 export declare function searchMethods(query: string): MethodSchema[];

package/dist/cdp/schema.js

@@ -220,10 +220,58 @@ export function getAllDomainSummaries() {
     const protocol = loadProtocol();
     return protocol.domains.map(buildDomainSummary);
 }
+/**
+ * Domain and method counts of the bundled protocol (for help text).
+ *
+ * @returns Number of domains, of methods overall, and of methods per domain
+ */
+export function getProtocolCounts() {
+    const summaries = getAllDomainSummaries();
+    return {
+        domains: summaries.length,
+        methods: summaries.reduce((total, domain) => total + domain.commandCount, 0),
+        methodsIn: (domain) => summaries.find((d) => d.name === domain)?.commandCount ?? 0,
+    };
+}
+/**
+ * Words agents search for that a method's name and description lack, e.g.
+ * "viewport" for `Emulation.setDeviceMetricsOverride`.
+ */
+const SEARCH_KEYWORDS = {
+    'Emulation.setDeviceMetricsOverride': [
+        'viewport',
+        'window size',
+        'screen size',
+        'resize',
+        'responsive',
+        'mobile',
+    ],
+    'Emulation.setEmulatedMedia': [
+        'color scheme',
+        'dark mode',
+        'light mode',
+        'prefers-color-scheme',
+        'reduced motion',
+        'print',
+    ],
+    'Browser.setWindowBounds': ['window size', 'resize'],
+};
+/**
+ * Lower-case text without spaces, hyphens and underscores, so "user agent"
+ * finds `setUserAgentOverride`.
+ *
+ * @param text - Text
+ * @returns Normalized text
+ */
+function searchable(text) {
+    return text.toLowerCase().replace(/[\s_-]+/g, '');
+}
 /**
  * Search methods by keyword (case-insensitive).
  *
- * Searches in method names and descriptions.
+ * Searches method names, extra keywords ({@link SEARCH_KEYWORDS}) and
+ * descriptions. Matches by name or keyword come first, then those found only
+ * in the description, each in protocol order.
  *
  * @param query - Search query
  * @returns Array of matching method schemas
@@ -232,23 +280,29 @@ export function getAllDomainSummaries() {
  * ```typescript
  * const cookies = searchMethods('cookie');
  * // Returns: Network.getCookies, Network.setCookie, Network.deleteCookies, etc.
+ * searchMethods('viewport')[0]?.name; // 'Emulation.setDeviceMetricsOverride'
  * ```
  */
 export function searchMethods(query) {
     const protocol = loadProtocol();
-    const results = [];
+    const named = [];
+    const described = [];
     const lowerQuery = query.toLowerCase();
+    const needle = searchable(query);
     protocol.domains.forEach((domain) => {
         if (!domain.commands)
             return;
         domain.commands.forEach((command) => {
-            const nameMatch = command.name.toLowerCase().includes(lowerQuery);
+            const keywords = SEARCH_KEYWORDS[`${domain.domain}.${command.name}`] ?? [];
+            const nameMatch = searchable(command.name).includes(needle) ||
+                keywords.some((keyword) => searchable(keyword).includes(needle));
             const descMatch = command.description?.toLowerCase().includes(lowerQuery) ?? false;
-            if (nameMatch || descMatch) {
-                results.push(buildMethodSchema(domain.domain, command));
-            }
+            if (nameMatch)
+                named.push(buildMethodSchema(domain.domain, command));
+            else if (descMatch)
+                described.push(buildMethodSchema(domain.domain, command));
         });
     });
-    return results;
+    return [...named, ...described];
 }
 //# sourceMappingURL=schema.js.map

package/dist/commands/cdp.js

@@ -1,9 +1,12 @@
 import { normalizeMethod } from '../cdp/protocol.js';
-import { getAllDomainSummaries, getDomainMethods, getDomainSummary, getMethodSchema, } from '../cdp/schema.js';
-import { runCommand } from '../commands/shared/CommandRunner.js';
+import { getAllDomainSummaries, getDomainMethods, getProtocolCounts, getDomainSummary, getMethodSchema, } from '../cdp/schema.js';
+import { runCommand } from './shared/CommandRunner.js';
+import { jsonOption } from './shared/commonOptions.js';
+import { CommandError } from '../errors/index.js';
 import { callCDP } from '../ipc/client.js';
 import { validateIPCResponse } from '../ipc/index.js';
-import { CommandError } from '../ui/errors/index.js';
+import { formatHint } from '../ui/messages/hints.js';
+import { sessionCommand } from '../ui/messages/sessionCommand.js';
 import { getErrorMessage } from '../utils/errors.js';
 import { EXIT_CODES } from '../utils/exitCodes.js';
 import { findSimilar } from '../utils/suggestions.js';
@@ -23,12 +26,19 @@ const DOMAIN_NOTES = {
     Tracing: 'Performance tracing. Call Tracing.start, perform actions, then Tracing.end. ' +
         'Data arrives via Tracing.dataCollected events.',
 };
+/**
+ * Domain and method counts of the bundled protocol, for the help text.
+ *
+ * @returns e.g. "59 domains, 675 methods"
+ */
+function cdpCountsText() {
+    const counts = getProtocolCounts();
+    return `${counts.domains} domains, ${counts.methods} methods`;
+}
 /**
  * Method-specific notes for methods with non-obvious behavior.
  */
 const METHOD_NOTES = {
-    'Audits.checkContrast': 'This method triggers contrast analysis but results are sent via Audits.issueAdded events. ' +
-        'Alternative: bdg dom eval with getComputedStyle() for direct contrast checking.',
     'Audits.enable': 'Enables the Audits domain. Issues will arrive via Audits.issueAdded events.',
     'Overlay.highlightNode': 'Highlights a node visually. Returns empty on success. Use Overlay.hideHighlight to clear.',
     'Profiler.start': 'Starts CPU profiling. Returns empty. Call Profiler.stop to get the profile data.',
@@ -76,7 +86,7 @@ function getMethodHint(methodName, result) {
 export function registerCdpCommand(program) {
     program
         .command('cdp')
-        .description('CDP protocol introspection and execution (53 domains, 300+ methods)\n' +
+        .description('CDP protocol introspection and execution\n' +
         '  Discovery: --list, --search, --describe\n' +
         '  Execution: case-insensitive (network.getcookies works)')
         .argument('[method]', 'CDP method name (e.g., Network.getCookies, network.getcookies)')
@@ -84,10 +94,12 @@ export function registerCdpCommand(program) {
         .option('--list', 'List all domains or methods in a domain')
         .option('--describe', 'Show method signature and parameters')
         .option('--search <query>', 'Search methods by keyword')
+        .addOption(jsonOption().hideHelp())
+        .addHelpText('after', () => `\nBundled protocol: ${cdpCountsText()}`)
         .action(async (method, options) => {
         await runCommand(async (opts) => {
             if (opts.search) {
-                return await handleSearch(opts.search);
+                return await handleSearch(opts.search, method);
             }
             if (opts.list && !method) {
                 return handleListDomains();
@@ -135,15 +147,46 @@ function findSimilarMethods(methodName, domain) {
         caseInsensitive: true,
     });
 }
+/**
+ * Did-you-mean for an unknown domain, or how to list them.
+ *
+ * @param domainName - Domain as typed
+ * @returns Suggestion
+ */
+function domainSuggestion(domainName) {
+    const [closest] = findSimilar(domainName, getAllDomainSummaries().map((summary) => summary.name));
+    return closest
+        ? `Did you mean: bdg cdp ${closest} --list?`
+        : 'Use: bdg cdp --list (to see all domains)';
+}
+/**
+ * For a method bdg refuses to run, what to use instead (shown as its example).
+ *
+ * @param methodName - Full method name, e.g. Page.captureScreenshot
+ * @returns Alternative command, or undefined for methods that run
+ */
+function blockedAlternative(methodName) {
+    const blocked = BLOCKED_CDP_METHODS[methodName];
+    return blocked && `${sessionCommand(blocked.alternative)} (raw ${methodName} is blocked)`;
+}
 /**
  * Handle search mode: Find methods by keyword.
  *
  * @param query - Search query
+ * @param domain - Domain to search in (`bdg cdp Network --search cookie`)
  * @returns Success result with matching methods
  */
-async function handleSearch(query) {
+async function handleSearch(query, domain) {
+    if (domain !== undefined && !getDomainSummary(domain)) {
+        return {
+            success: false,
+            error: `Domain '${domain}' not found`,
+            exitCode: EXIT_CODES.INVALID_ARGUMENTS,
+            errorContext: { suggestion: domainSuggestion(domain) },
+        };
+    }
     const { searchMethods } = await import('../cdp/schema.js');
-    const results = searchMethods(query);
+    const results = searchMethods(query).filter((m) => domain === undefined || m.domain.toLowerCase() === domain.toLowerCase());
     return {
         success: true,
         data: {
@@ -157,7 +200,7 @@ async function handleSearch(query) {
                 experimental: m.experimental,
                 deprecated: m.deprecated,
                 parameterCount: m.parameters.length,
-                example: m.example?.command,
+                example: blockedAlternative(m.name) ?? m.example?.command,
             })),
         },
     };
@@ -199,7 +242,7 @@ function handleListDomainMethods(domainName) {
             error: `Domain '${domainName}' not found`,
             exitCode: EXIT_CODES.INVALID_ARGUMENTS,
             errorContext: {
-                suggestion: 'Use: bdg cdp --list (to see all domains)',
+                suggestion: domainSuggestion(domainName),
             },
         };
     }
@@ -226,7 +269,7 @@ function handleListDomainMethods(domainName) {
                     name: r.name,
                     type: r.type,
                 })),
-                example: m.example?.command,
+                example: blockedAlternative(m.name) ?? m.example?.command,
             })),
         },
     };
@@ -322,19 +365,29 @@ function handleDescribeMethod(methodName) {
                 description: r.description,
                 items: r.items,
             })),
-            example: schema.example,
+            example: blockedAlternative(schema.name)
+                ? { command: blockedAlternative(schema.name) }
+                : schema.example,
         },
     };
 }
 /**
- * CDP methods blocked from raw execution due to output issues.
- * These methods return large binary data that corrupts terminal/agent sessions.
+ * CDP methods blocked from raw execution: they return large binary data that
+ * corrupts terminal/agent sessions, or end the session behind bdg's back.
  */
 const BLOCKED_CDP_METHODS = {
     'Page.captureScreenshot': {
         alternative: 'bdg dom screenshot [path]',
         reason: 'Returns large base64 data that corrupts terminal sessions',
     },
+    'Page.close': {
+        alternative: 'bdg stop',
+        reason: 'Closes the page under the session, which then ends',
+    },
+    'Browser.close': {
+        alternative: 'bdg stop',
+        reason: 'Closes Chrome under the session, which then ends without saving its state',
+    },
 };
 /**
  * Handle execute method mode: Call CDP method.
@@ -345,14 +398,14 @@ const BLOCKED_CDP_METHODS = {
  */
 async function handleExecuteMethod(methodName, paramsJson) {
     const normalized = normalizeMethod(methodName);
-    // Block methods that return large binary data
-    // Output error to stderr only and exit - no JSON output to avoid confusing pipelines
     if (normalized && BLOCKED_CDP_METHODS[normalized]) {
         const blocked = BLOCKED_CDP_METHODS[normalized];
-        console.error(`Error: ${normalized} is blocked via raw CDP`);
-        console.error(`Reason: ${blocked.reason}`);
-        console.error(`Use: ${blocked.alternative}`);
-        process.exit(1);
+        return {
+            success: false,
+            error: `${normalized} is blocked via raw CDP: ${blocked.reason}`,
+            exitCode: EXIT_CODES.INVALID_ARGUMENTS,
+            errorContext: { suggestion: `Use: ${sessionCommand(blocked.alternative)}` },
+        };
     }
     if (!normalized) {
         const similar = findSimilarMethods(methodName);
@@ -379,7 +432,7 @@ async function handleExecuteMethod(methodName, paramsJson) {
         catch (error) {
             return {
                 success: false,
-                error: `Error parsing --params: ${getErrorMessage(error)}. Parameters must be valid JSON.`,
+                error: `Invalid --params JSON: ${getErrorMessage(error)}`,
                 exitCode: EXIT_CODES.INVALID_ARGUMENTS,
                 errorContext: {
                     suggestion: `Use: bdg cdp ${normalized} --describe (to see parameter schema)`,
@@ -398,7 +451,7 @@ async function handleExecuteMethod(methodName, paramsJson) {
         },
     };
     if (response.data?.hint) {
-        result.hint = response.data.hint;
+        result.hint = formatHint(response.data.hint);
     }
     const methodHint = getMethodHint(normalized, cdpResult);
     if (methodHint) {

package/dist/commands/cleanup.d.ts

@@ -1,4 +1,15 @@
 import type { Command } from 'commander';
+import { type ErrorWithSuggestion } from '../errors/messages.js';
+/**
+ * Why the session directory must not be deleted after cleanup: its daemon
+ * still runs, cleanup reported problems, or its Chrome has not exited.
+ *
+ * @param chromePid - The session's Chrome as found before cleanup, or null
+ * @param warnings - Warnings from cleanup
+ * @param exitWaitMs - How long to wait for that Chrome to exit
+ * @returns Error and suggestion, or null when the directory may be deleted
+ */
+export declare function purgeBlocker(chromePid: number | null, warnings: string[], exitWaitMs?: number): Promise<ErrorWithSuggestion | null>;
 /**
  * Register cleanup command
  *

package/dist/commands/cleanup.js

@@ -1,9 +1,15 @@
-import { runCommand } from '../commands/shared/CommandRunner.js';
-import { jsonOption } from '../commands/shared/commonOptions.js';
-import { performSessionCleanup } from '../session/cleanup.js';
-import { readPid } from '../session/pid.js';
+import * as fs from 'fs';
+import { runCommand } from './shared/CommandRunner.js';
+import { jsonOption } from './shared/commonOptions.js';
+import { purgeNeedsNamedSessionError, purgeRefusedError, sessionDirIsFileError, } from '../errors/messages.js';
+import { isSessionChrome } from '../session/cleanup/staleSession.js';
+import { performSessionCleanup } from '../session/cleanup/userCommands.js';
+import { isDaemonAlive } from '../session/daemonSocket.js';
+import { getSessionDir, getSessionFilePath, getSessionName } from '../session/paths.js';
+import { readDaemonPid, readPidFromFile } from '../session/pid.js';
 import { joinLines } from '../ui/formatting.js';
-import { sessionFilesCleanedMessage, sessionOutputRemovedMessage, sessionDirectoryCleanMessage, noSessionFilesMessage, sessionStillActiveError, warningMessage, } from '../ui/messages/commands.js';
+import { sessionFilesCleanedMessage, sessionOutputRemovedMessage, sessionDirectoryCleanMessage, sessionDirectoryPurgedMessage, noSessionFilesMessage, sessionStillActiveError, sessionStillActiveSuggestion, warningMessage, } from '../ui/messages/commands.js';
+import { delay } from '../utils/async.js';
 import { EXIT_CODES } from '../utils/exitCodes.js';
 import { isProcessAlive } from '../utils/process.js';
 /**
@@ -15,6 +21,158 @@ function formatCleanup(data) {
     const { cleaned } = data;
     return joinLines(cleaned.session && sessionFilesCleanedMessage(), cleaned.output && sessionOutputRemovedMessage(), ...(data.warnings ?? []).map((warning) => warningMessage(warning)), '', data.message);
 }
+/**
+ * Delete the selected named session's directory (Chrome profile, logs, port).
+ *
+ * @returns The deleted directory, or undefined if there was none
+ */
+function purgeSessionDir() {
+    const dir = getSessionDir();
+    if (!fs.existsSync(dir))
+        return undefined;
+    fs.rmSync(dir, { recursive: true, force: true, maxRetries: 3 });
+    return dir;
+}
+/** How long `--purge` waits for a killed Chrome to exit */
+const PURGE_CHROME_EXIT_WAIT_MS = 5000;
+/**
+ * The running Chrome bdg launched for the selected session (from chrome.pid,
+ * verified by its marker flag).
+ *
+ * @returns Chrome PID, or null
+ */
+function liveSessionChromePid() {
+    const pid = readPidFromFile(getSessionFilePath('CHROME_PID'));
+    if (pid === null || !isProcessAlive(pid))
+        return null;
+    return isSessionChrome(pid, getSessionDir()) ? pid : null;
+}
+/**
+ * Wait until a process has exited.
+ *
+ * @param pid - Process ID
+ * @param timeoutMs - Longest wait
+ * @returns True if it exited
+ */
+async function waitForExit(pid, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (isProcessAlive(pid) && Date.now() < deadline)
+        await delay(50);
+    return !isProcessAlive(pid);
+}
+/**
+ * Why the session directory must not be deleted after cleanup: its daemon
+ * still runs, cleanup reported problems, or its Chrome has not exited.
+ *
+ * @param chromePid - The session's Chrome as found before cleanup, or null
+ * @param warnings - Warnings from cleanup
+ * @param exitWaitMs - How long to wait for that Chrome to exit
+ * @returns Error and suggestion, or null when the directory may be deleted
+ */
+export async function purgeBlocker(chromePid, warnings, exitWaitMs = PURGE_CHROME_EXIT_WAIT_MS) {
+    const dir = getSessionDir();
+    if (await isDaemonAlive())
+        return purgeRefusedError(dir, 'its daemon is still running');
+    if (warnings.length > 0)
+        return purgeRefusedError(dir, warnings.join('; '));
+    if (chromePid !== null && !(await waitForExit(chromePid, exitWaitMs))) {
+        return purgeRefusedError(dir, `its Chrome (PID ${chromePid}) is still running`);
+    }
+    return null;
+}
+/**
+ * Delete the session directory unless {@link purgeBlocker} objects.
+ *
+ * @param chromePid - The session's Chrome as found before cleanup, or null
+ * @param warnings - Warnings from cleanup
+ * @returns The deleted directory (undefined if there was none), or the refusal
+ */
+async function purge(chromePid, warnings) {
+    const refusal = await purgeBlocker(chromePid, warnings);
+    if (refusal)
+        return { refusal };
+    const purged = purgeSessionDir();
+    return purged === undefined ? {} : { purged };
+}
+/**
+ * Why cleanup cannot run: the session directory is a file, `--purge` lacks a
+ * named session, or the session is still running (without `--force`).
+ *
+ * @param opts - Cleanup options
+ * @returns Error result, or null when cleanup may run
+ */
+async function cleanupBlocker(opts) {
+    const dir = getSessionDir();
+    if (fs.existsSync(dir) && !fs.statSync(dir).isDirectory()) {
+        const err = sessionDirIsFileError(dir);
+        return {
+            success: false,
+            error: err.message,
+            exitCode: EXIT_CODES.SESSION_FILE_ERROR,
+            errorContext: { suggestion: err.suggestion },
+        };
+    }
+    if (opts.purge && getSessionName() === null) {
+        const err = purgeNeedsNamedSessionError();
+        return {
+            success: false,
+            error: err.message,
+            exitCode: EXIT_CODES.INVALID_ARGUMENTS,
+            errorContext: { suggestion: err.suggestion },
+        };
+    }
+    if (!opts.force && !opts.aggressive && (await isDaemonAlive())) {
+        return {
+            success: false,
+            error: sessionStillActiveError(readDaemonPid() ?? 0),
+            exitCode: EXIT_CODES.RESOURCE_BUSY,
+            errorContext: {
+                suggestion: sessionStillActiveSuggestion(getSessionName()),
+                warning: 'Force cleanup kills the running daemon and its Chrome',
+            },
+        };
+    }
+    return null;
+}
+/**
+ * Clean up the selected session (and delete its directory with `--purge`).
+ *
+ * @param opts - Cleanup options
+ * @returns Command result
+ */
+async function cleanupSession(opts) {
+    const blocker = await cleanupBlocker(opts);
+    if (blocker)
+        return blocker;
+    const chromePid = opts.purge ? liveSessionChromePid() : null;
+    const { cleaned, warnings } = await performSessionCleanup({
+        force: Boolean(opts.force) || Boolean(opts.aggressive),
+        removeOutput: opts.removeOutput,
+    });
+    const { purged, refusal } = opts.purge ? await purge(chromePid, warnings) : {};
+    if (refusal) {
+        return {
+            success: false,
+            error: refusal.message,
+            exitCode: EXIT_CODES.RESOURCE_CONFLICT,
+            errorContext: { suggestion: refusal.suggestion },
+        };
+    }
+    const didCleanup = Object.values(cleaned).some(Boolean) || purged !== undefined;
+    return {
+        success: true,
+        data: {
+            cleaned,
+            ...(purged !== undefined && { purged }),
+            message: !didCleanup
+                ? noSessionFilesMessage()
+                : purged !== undefined
+                    ? sessionDirectoryPurgedMessage(purged)
+                    : sessionDirectoryCleanMessage(),
+            ...(warnings.length > 0 && { warnings }),
+        },
+    };
+}
 /**
  * Register cleanup command
  *
@@ -24,59 +182,13 @@ export function registerCleanupCommand(program) {
     program
         .command('cleanup')
         .description('Clean up stale session files')
-        .option('-f, --force', 'Force cleanup even if session appears active', false)
+        .option('-f, --force', 'Kill a running (possibly hung) session, then clean up', false)
         .option('--remove-output', 'Also remove session.json output file', false)
-        .option('--aggressive', 'Kill orphaned daemon processes and all stale Chrome instances', false)
+        .option('--aggressive', 'Alias for --force (kept for compatibility)', false)
+        .option('--purge', "Also delete a named session's directory (Chrome profile, logs, port); needs --session", false)
         .addOption(jsonOption())
         .action(async (options) => {
-        await runCommand(async (opts) => {
-            const pid = readPid();
-            if (pid) {
-                const isAlive = isProcessAlive(pid);
-                if (isAlive && !opts.force) {
-                    return {
-                        success: false,
-                        error: sessionStillActiveError(pid),
-                        exitCode: EXIT_CODES.RESOURCE_BUSY,
-                        errorContext: {
-                            suggestion: 'Stop gracefully: bdg stop\nForce cleanup: bdg cleanup --force',
-                            warning: 'Force cleanup will remove session files but will NOT kill the running process',
-                        },
-                    };
-                }
-            }
-            const cleanupResult = await performSessionCleanup({
-                force: opts.force,
-                aggressive: opts.aggressive,
-                removeOutput: opts.removeOutput,
-            });
-            const didCleanup = cleanupResult.cleaned.session ||
-                cleanupResult.cleaned.chrome ||
-                cleanupResult.cleaned.daemons ||
-                cleanupResult.cleaned.output;
-            if (!didCleanup) {
-                return {
-                    success: true,
-                    data: {
-                        cleaned: { session: false, output: false, chrome: false, daemons: false },
-                        message: noSessionFilesMessage(),
-                    },
-                };
-            }
-            return {
-                success: true,
-                data: {
-                    cleaned: {
-                        session: cleanupResult.cleaned.session,
-                        output: cleanupResult.cleaned.output,
-                        chrome: cleanupResult.cleaned.chrome,
-                        daemons: cleanupResult.cleaned.daemons,
-                    },
-                    message: sessionDirectoryCleanMessage(),
-                    ...(cleanupResult.warnings.length > 0 && { warnings: cleanupResult.warnings }),
-                },
-            };
-        }, options, formatCleanup);
+        await runCommand(cleanupSession, options, formatCleanup);
     });
 }
 //# sourceMappingURL=cleanup.js.map