devharness 0.8.0

package/build/debugger-aware-wrapper.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Debugger-Aware Action Wrapper
+ * Wraps Puppeteer/CDP actions to detect and handle breakpoint pauses
+ */
+import type { CDPManager } from './cdp-manager.js';
+export interface ActionResult<T = any> {
+    success: boolean;
+    pausedAtBreakpoint?: boolean;
+    pauseInfo?: {
+        url: string;
+        lineNumber: number;
+        columnNumber?: number;
+        functionName: string;
+        callStackDepth: number;
+    };
+    result?: T;
+    error?: string;
+}
+/**
+ * Execute an action with pause detection
+ *
+ * If the debugger is already paused, returns immediately with error.
+ * Otherwise, races the action against pause detection.
+ * If a breakpoint is hit during execution, returns pause info immediately.
+ *
+ * @param cdpManager - The CDP manager instance
+ * @param action - The async action to execute
+ * @param actionName - Name of the action (for error messages)
+ * @param timeout - Timeout in ms (default: 5000)
+ * @returns ActionResult with either success/result or pause info
+ */
+export declare function executeWithPauseDetection<T = any>(cdpManager: CDPManager, action: () => Promise<T>, actionName: string, timeout?: number): Promise<ActionResult<T>>;
+/**
+ * Format action result for MCP tool response
+ */
+export declare function formatActionResult(result: ActionResult, actionName: string, details?: any): any;
+//# sourceMappingURL=debugger-aware-wrapper.d.ts.map

package/build/debugger-aware-wrapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debugger-aware-wrapper.d.ts","sourceRoot":"","sources":["../src/debugger-aware-wrapper.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAGnD,MAAM,WAAW,YAAY,CAAC,CAAC,GAAG,GAAG;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,SAAS,CAAC,EAAE;QACV,GAAG,EAAE,MAAM,CAAC;QACZ,UAAU,EAAE,MAAM,CAAC;QACnB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,YAAY,EAAE,MAAM,CAAC;QACrB,cAAc,EAAE,MAAM,CAAC;KACxB,CAAC;IACF,MAAM,CAAC,EAAE,CAAC,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,yBAAyB,CAAC,CAAC,GAAG,GAAG,EACrD,UAAU,EAAE,UAAU,EACtB,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACxB,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,MAAa,GACrB,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CA4E1B;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,GAAG,GAAG,CAgC/F"}

package/build/debugger-aware-wrapper.js

@@ -0,0 +1,128 @@
+/**
+ * Debugger-Aware Action Wrapper
+ * Wraps Puppeteer/CDP actions to detect and handle breakpoint pauses
+ */
+import { isAbortError } from './utils/abort.js';
+/**
+ * Execute an action with pause detection
+ *
+ * If the debugger is already paused, returns immediately with error.
+ * Otherwise, races the action against pause detection.
+ * If a breakpoint is hit during execution, returns pause info immediately.
+ *
+ * @param cdpManager - The CDP manager instance
+ * @param action - The async action to execute
+ * @param actionName - Name of the action (for error messages)
+ * @param timeout - Timeout in ms (default: 5000)
+ * @returns ActionResult with either success/result or pause info
+ */
+export async function executeWithPauseDetection(cdpManager, action, actionName, timeout = 5000) {
+    // Pre-check: If already paused, return immediately
+    if (cdpManager.isPaused()) {
+        const pauseInfo = cdpManager.getPausedInfo();
+        return {
+            success: false,
+            pausedAtBreakpoint: true,
+            error: `Cannot perform ${actionName} while execution is paused at a breakpoint`,
+            pauseInfo: pauseInfo.location ? {
+                url: pauseInfo.location.url,
+                lineNumber: pauseInfo.location.lineNumber,
+                columnNumber: pauseInfo.location.columnNumber,
+                functionName: pauseInfo.location.functionName,
+                callStackDepth: pauseInfo.callStack?.length || 0,
+            } : undefined,
+        };
+    }
+    try {
+        // Race the action against pause detection
+        const result = await Promise.race([
+            // The actual action
+            action().then(res => ({ type: 'success', result: res })),
+            // Pause detection
+            cdpManager.waitForPause(timeout).then(() => ({ type: 'paused' })),
+        ]);
+        if (result.type === 'paused') {
+            // Breakpoint was hit during execution
+            const pauseInfo = cdpManager.getPausedInfo();
+            return {
+                success: true,
+                pausedAtBreakpoint: true,
+                pauseInfo: pauseInfo.location ? {
+                    url: pauseInfo.location.url,
+                    lineNumber: pauseInfo.location.lineNumber,
+                    columnNumber: pauseInfo.location.columnNumber,
+                    functionName: pauseInfo.location.functionName,
+                    callStackDepth: pauseInfo.callStack?.length || 0,
+                } : undefined,
+            };
+        }
+        else {
+            // Action completed successfully without hitting breakpoint
+            return {
+                success: true,
+                pausedAtBreakpoint: false,
+                result: result.result,
+            };
+        }
+    }
+    catch (error) {
+        // A cancellation is not an action failure - swallowing it here would
+        // convert the user's cancel into an "ELEMENT_NOT_FOUND"-style error result
+        // and let the caller carry on (#110). Rethrow; the tool handler/executor
+        // classifies it.
+        if (isAbortError(error)) {
+            throw error;
+        }
+        // Action failed - report the actual error
+        // Note: Even if we're paused, the action still failed with an error
+        const isPaused = cdpManager.isPaused();
+        const pauseInfo = isPaused ? cdpManager.getPausedInfo() : null;
+        return {
+            success: false,
+            pausedAtBreakpoint: isPaused,
+            error: `${actionName} failed: ${error.message || error}`,
+            pauseInfo: pauseInfo?.location ? {
+                url: pauseInfo.location.url,
+                lineNumber: pauseInfo.location.lineNumber,
+                columnNumber: pauseInfo.location.columnNumber,
+                functionName: pauseInfo.location.functionName,
+                callStackDepth: pauseInfo.callStack?.length || 0,
+            } : undefined,
+        };
+    }
+}
+/**
+ * Format action result for MCP tool response
+ */
+export function formatActionResult(result, actionName, details) {
+    if (result.pausedAtBreakpoint && result.pauseInfo) {
+        return {
+            action: actionName,
+            pausedAtBreakpoint: true,
+            message: `Execution paused at breakpoint during ${actionName}`,
+            location: {
+                url: result.pauseInfo.url,
+                line: result.pauseInfo.lineNumber,
+                column: result.pauseInfo.columnNumber,
+                function: result.pauseInfo.functionName,
+            },
+            callStackDepth: result.pauseInfo.callStackDepth,
+            hint: 'Use getCallStack() to inspect, stepOver()/stepInto() to continue debugging, or resume() to continue execution',
+            ...details,
+        };
+    }
+    if (!result.success) {
+        return {
+            action: actionName,
+            error: result.error,
+            ...details,
+        };
+    }
+    return {
+        action: actionName,
+        success: true,
+        ...details,
+        ...(result.result ? { result: result.result } : {}),
+    };
+}
+//# sourceMappingURL=debugger-aware-wrapper.js.map

package/build/debugger-aware-wrapper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"debugger-aware-wrapper.js","sourceRoot":"","sources":["../src/debugger-aware-wrapper.ts"],"names":[],"mappings":"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"}

package/build/dom-change-monitor.d.ts

@@ -0,0 +1,92 @@
+/**
+ * DOM Change Monitor
+ * Uses MutationObserver to track DOM changes during browser actions
+ * Replaces snapshot-based diffing with real-time observation
+ */
+/**
+ * Information about a changed element
+ */
+export interface ElementChange {
+    tag: string;
+    selector: string;
+    text?: string;
+    context?: string;
+}
+/**
+ * Text content change
+ */
+export interface TextChange {
+    selector: string;
+    before: string;
+    after: string;
+}
+/**
+ * Result of DOM change observation
+ */
+export interface DOMChanges {
+    added: ElementChange[];
+    removed: ElementChange[];
+    shown: ElementChange[];
+    hidden: ElementChange[];
+    textChanged: TextChange[];
+    settled: boolean;
+    duration: number;
+    mutationCount: number;
+}
+/**
+ * Configuration for change detection
+ */
+export interface ChangeDetectionConfig {
+    enabled: boolean;
+    settleTimeout: number;
+    quietPeriod: number;
+    navigationTimeout: number;
+}
+export declare const DEFAULT_CHANGE_DETECTION_CONFIG: ChangeDetectionConfig;
+/**
+ * DOM Change Monitor
+ * Manages MutationObserver injection and result collection
+ */
+export declare class DOMChangeMonitor {
+    private sessions;
+    /**
+     * Start observing DOM changes before an action
+     */
+    startObserving(connectionRef: string, page: any): Promise<void>;
+    /**
+     * Stop observing and collect results
+     * Waits for mutations to settle before collecting
+     */
+    stopObserving(connectionRef: string, options?: {
+        settleTimeout?: number;
+        quietPeriod?: number;
+        /** Optional cancellation (#110): aborting ends the settle WAIT early
+         *  (reported as settled: false) - results observed so far are still
+         *  collected and the observer is still cleaned up. It never throws:
+         *  the action's dispatches already happened, so callers report what
+         *  was seen and stop promptly. */
+        signal?: AbortSignal;
+    }): Promise<DOMChanges | null>;
+    /**
+     * Wait for mutations to settle (no new mutations for quietPeriod)
+     */
+    private waitForSettle;
+    /**
+     * Cleanup browser-side observer
+     */
+    private cleanup;
+    /**
+     * Check if currently observing for a connection
+     */
+    isObserving(connectionRef: string): boolean;
+    /**
+     * Clear all sessions (for shutdown)
+     */
+    clearAll(): Promise<void>;
+}
+export declare const domChangeMonitor: DOMChangeMonitor;
+/**
+ * Format DOM changes for display in action response
+ */
+export declare function formatDOMChanges(changes: DOMChanges | null): string;
+//# sourceMappingURL=dom-change-monitor.d.ts.map

package/build/dom-change-monitor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dom-change-monitor.d.ts","sourceRoot":"","sources":["../src/dom-change-monitor.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,OAAO,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,eAAO,MAAM,+BAA+B,EAAE,qBAK7C,CAAC;AAUF;;;GAGG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAsC;IAEtD;;OAEG;IACG,cAAc,CAAC,aAAa,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IAoOrE;;;OAGG;IACG,aAAa,CACjB,aAAa,EAAE,MAAM,EACrB,OAAO,GAAE;QACP,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB;;;;0CAIkC;QAClC,MAAM,CAAC,EAAE,WAAW,CAAC;KACjB,GACL,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAyE7B;;OAEG;YACW,aAAa;IAkC3B;;OAEG;YACW,OAAO;IAoBrB;;OAEG;IACH,WAAW,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO;IAI3C;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAKhC;AAGD,eAAO,MAAM,gBAAgB,kBAAyB,CAAC;AAEvD;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,UAAU,GAAG,IAAI,GAAG,MAAM,CAuDnE"}