@jshookmcp/jshook 0.2.0 → 0.2.1

package/dist/src/modules/collector/CodeCollector.js

@@ -1,4 +1,7 @@
 import { existsSync } from 'fs';
+import { readFile } from 'fs/promises';
+import { homedir } from 'os';
+import { join } from 'path';
 import puppeteer from 'rebrowser-puppeteer-core';
 import { logger } from '../../utils/logger.js';
 import { PrerequisiteError } from '../../errors/PrerequisiteError.js';
@@ -15,10 +18,12 @@ export class CodeCollector {
     collectedUrls = new Set();
     initPromise = null;
     collectLock = null;
+    connectAttemptId = 0;
     MAX_COLLECTED_URLS;
     MAX_FILES_PER_COLLECT;
     MAX_RESPONSE_SIZE;
     MAX_SINGLE_FILE_SIZE;
+    CONNECT_TIMEOUT_MS;
     viewport;
     userAgent;
     collectedFilesCache = new Map();
@@ -31,12 +36,14 @@ export class CodeCollector {
     activePageIndex = null;
     currentHeadless = null;
     explicitlyClosed = false;
+    connectedToExistingBrowser = false;
     constructor(config) {
         this.config = config;
         this.MAX_COLLECTED_URLS = config.maxCollectedUrls ?? 10000;
         this.MAX_FILES_PER_COLLECT = config.maxFilesPerCollect ?? 200;
         this.MAX_RESPONSE_SIZE = config.maxTotalContentSize ?? 512 * 1024;
         this.MAX_SINGLE_FILE_SIZE = config.maxSingleFileSize ?? 200 * 1024;
+        this.CONNECT_TIMEOUT_MS = 15000;
         this.viewport = config.viewport ?? { width: 1920, height: 1080 };
         this.userAgent =
             config.userAgent ??
@@ -139,11 +146,13 @@ export class CodeCollector {
         }
         logger.info('Initializing browser with anti-detection...');
         this.browser = await puppeteer.launch(launchOptions);
+        this.connectedToExistingBrowser = false;
         this.currentHeadless = useHeadless === undefined ? true : useHeadless !== false;
         this.browser.on('disconnected', () => {
             logger.warn('Browser disconnected');
             this.browser = null;
             this.currentHeadless = null;
+            this.connectedToExistingBrowser = false;
             if (this.cdpSession) {
                 this.cdpSession = null;
                 this.cdpListeners = {};
@@ -172,17 +181,47 @@ export class CodeCollector {
         this.explicitlyClosed = true;
         this.activePageIndex = null;
         const browser = this.browser;
+        const disconnectOnly = this.connectedToExistingBrowser;
         this.browser = null;
         this.currentHeadless = null;
+        this.connectedToExistingBrowser = false;
         if (this.cdpSession) {
             this.cdpSession = null;
             this.cdpListeners = {};
         }
         if (browser) {
-            await browser.close();
+            if (disconnectOnly) {
+                await browser.disconnect();
+            }
+            else {
+                await browser.close();
+            }
         }
         logger.info('Browser closed and all data cleared');
     }
+    getPageTargets() {
+        if (!this.browser) {
+            return [];
+        }
+        return this.browser.targets().filter((target) => target.type() === 'page');
+    }
+    async resolvePageTargetHandle(target, timeoutMs = 5000) {
+        const page = await Promise.race([
+            target.page(),
+            new Promise((_, reject) => {
+                setTimeout(() => {
+                    reject(new PrerequisiteError(`Timed out after ${timeoutMs}ms while resolving a Puppeteer Page handle from the attached Chrome target.`));
+                }, timeoutMs);
+            }),
+        ]);
+        if (!page) {
+            throw new PrerequisiteError('Attached browser target does not expose a Puppeteer Page handle in the current Chrome remote debugging mode.');
+        }
+        return page;
+    }
+    isExistingBrowserConnection() {
+        return this.connectedToExistingBrowser;
+    }
     async getActivePage() {
         if (!this.browser) {
             if (this.explicitlyClosed) {
@@ -195,49 +234,73 @@ export class CodeCollector {
                 throw new PrerequisiteError(`Browser not available: ${error instanceof Error ? error.message : String(error)}`);
             }
         }
-        const pages = await this.browser.pages();
-        if (pages.length === 0) {
+        const pageTargets = this.getPageTargets();
+        if (pageTargets.length === 0) {
             return await this.browser.newPage();
         }
-        if (this.activePageIndex !== null && this.activePageIndex < pages.length) {
-            return pages[this.activePageIndex];
+        if (this.activePageIndex !== null && this.activePageIndex < pageTargets.length) {
+            return await this.resolvePageTargetHandle(pageTargets[this.activePageIndex]);
         }
-        const lastPage = pages[pages.length - 1];
-        if (!lastPage) {
+        const lastTarget = pageTargets[pageTargets.length - 1];
+        if (!lastTarget) {
             throw new Error('Failed to get active page');
         }
-        return lastPage;
+        return await this.resolvePageTargetHandle(lastTarget);
     }
     async listPages() {
         if (!this.browser) {
             return [];
         }
-        const pages = await this.browser.pages();
-        const results = await Promise.all(pages.map(async (page, index) => {
-            let url = '';
-            let title = '';
+        const targets = this.getPageTargets();
+        return targets.map((target, index) => ({
+            index,
+            url: target.url(),
+            title: '',
+        }));
+    }
+    async listResolvedPages(timeoutMs = 1500) {
+        if (!this.browser) {
+            return [];
+        }
+        const targets = this.getPageTargets();
+        const pages = await Promise.all(targets.map(async (target, index) => {
             try {
-                url = page.url();
+                const page = await this.resolvePageTargetHandle(target, timeoutMs);
+                let title = '';
+                try {
+                    title = await Promise.race([
+                        page.title(),
+                        new Promise((resolve) => {
+                            setTimeout(() => resolve(''), timeoutMs);
+                        }),
+                    ]);
+                }
+                catch {
+                    title = '';
+                }
+                return {
+                    index,
+                    url: target.url(),
+                    title,
+                    page,
+                };
             }
-            catch { }
-            try {
-                title = await page.title();
+            catch {
+                return null;
             }
-            catch { }
-            return { index, url, title };
         }));
-        return results;
+        return pages.filter((page) => page !== null);
     }
     async selectPage(index) {
         if (!this.browser) {
             throw new Error('Browser not connected');
         }
-        const pages = await this.browser.pages();
+        const pages = await this.listPages();
         if (index < 0 || index >= pages.length) {
             throw new Error(`Page index ${index} out of range (0-${pages.length - 1})`);
         }
         this.activePageIndex = index;
-        logger.info(`Active page set to index ${index}: ${pages[index].url()}`);
+        logger.info(`Active page set to index ${index}: ${pages[index].url}`);
     }
     async createPage(url) {
         if (!this.browser) {
@@ -292,8 +355,8 @@ export class CodeCollector {
             };
         }
         try {
-            const pages = await this.browser.pages();
             const version = await this.browser.version();
+            const pages = this.getPageTargets();
             return {
                 running: true,
                 pagesCount: pages.length,
@@ -347,7 +410,189 @@ export class CodeCollector {
     async collectPageMetadata(page) {
         return collectPageMetadataImpl(page);
     }
-    async connect(endpoint) {
+    resolveDefaultChromeUserDataDir(channel = 'stable') {
+        const home = homedir();
+        if (process.platform === 'win32') {
+            const localAppData = process.env.LOCALAPPDATA ?? join(home, 'AppData', 'Local');
+            switch (channel) {
+                case 'beta':
+                    return join(localAppData, 'Google', 'Chrome Beta', 'User Data');
+                case 'dev':
+                    return join(localAppData, 'Google', 'Chrome Dev', 'User Data');
+                case 'canary':
+                    return join(localAppData, 'Google', 'Chrome SxS', 'User Data');
+                case 'stable':
+                default:
+                    return join(localAppData, 'Google', 'Chrome', 'User Data');
+            }
+        }
+        if (process.platform === 'darwin') {
+            const appSupport = join(home, 'Library', 'Application Support');
+            switch (channel) {
+                case 'beta':
+                    return join(appSupport, 'Google', 'Chrome Beta');
+                case 'dev':
+                    return join(appSupport, 'Google', 'Chrome Dev');
+                case 'canary':
+                    return join(appSupport, 'Google', 'Chrome Canary');
+                case 'stable':
+                default:
+                    return join(appSupport, 'Google', 'Chrome');
+            }
+        }
+        const configHome = process.env.XDG_CONFIG_HOME ?? join(home, '.config');
+        switch (channel) {
+            case 'beta':
+                return join(configHome, 'google-chrome-beta');
+            case 'dev':
+                return join(configHome, 'google-chrome-unstable');
+            case 'canary':
+                return join(configHome, 'google-chrome-canary');
+            case 'stable':
+            default:
+                return join(configHome, 'google-chrome');
+        }
+    }
+    async resolveAutoConnectWsEndpoint(options) {
+        const channel = options.channel ?? 'stable';
+        const userDataDir = options.userDataDir ?? this.resolveDefaultChromeUserDataDir(channel);
+        const devToolsActivePortPath = join(userDataDir, 'DevToolsActivePort');
+        let fileContent;
+        try {
+            fileContent = await readFile(devToolsActivePortPath, 'utf8');
+        }
+        catch (error) {
+            throw new Error(`Could not read DevToolsActivePort from "${devToolsActivePortPath}". Check if Chrome is running from this profile and remote debugging is enabled at chrome://inspect/#remote-debugging.`, { cause: error });
+        }
+        const [rawPort, rawPath] = fileContent
+            .split(/\r?\n/u)
+            .map(line => line.trim())
+            .filter(Boolean);
+        if (!rawPort || !rawPath) {
+            throw new Error(`Invalid DevToolsActivePort contents found in "${devToolsActivePortPath}".`);
+        }
+        const port = Number.parseInt(rawPort, 10);
+        if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+            throw new Error(`Invalid remote debugging port "${rawPort}" in "${devToolsActivePortPath}".`);
+        }
+        return `ws://127.0.0.1:${port}${rawPath}`;
+    }
+    async resolveConnectOptions(endpointOrOptions) {
+        if (typeof endpointOrOptions === 'string') {
+            const endpoint = endpointOrOptions.trim();
+            if (!endpoint) {
+                throw new Error('Connection endpoint cannot be empty.');
+            }
+            return endpoint.startsWith('ws://') || endpoint.startsWith('wss://')
+                ? { browserWSEndpoint: endpoint }
+                : { browserURL: endpoint };
+        }
+        if (endpointOrOptions.wsEndpoint) {
+            return { browserWSEndpoint: endpointOrOptions.wsEndpoint };
+        }
+        if (endpointOrOptions.browserURL) {
+            return { browserURL: endpointOrOptions.browserURL };
+        }
+        if (endpointOrOptions.autoConnect ||
+            endpointOrOptions.userDataDir ||
+            endpointOrOptions.channel) {
+            return {
+                browserWSEndpoint: await this.resolveAutoConnectWsEndpoint(endpointOrOptions),
+            };
+        }
+        throw new Error('browserURL, wsEndpoint, autoConnect, userDataDir, or channel is required to connect to an existing browser.');
+    }
+    isAutoConnectRequest(endpointOrOptions) {
+        return (typeof endpointOrOptions !== 'string' &&
+            Boolean(endpointOrOptions.autoConnect ||
+                endpointOrOptions.userDataDir ||
+                endpointOrOptions.channel));
+    }
+    getUnknownErrorMessage(error) {
+        if (error instanceof Error) {
+            return error.message;
+        }
+        if (typeof error === 'object' && error !== null) {
+            const directMessage = 'message' in error && typeof error.message === 'string' ? error.message.trim() : '';
+            if (directMessage) {
+                return directMessage;
+            }
+            const nestedError = 'error' in error ? error.error : undefined;
+            if (nestedError instanceof Error && nestedError.message) {
+                return nestedError.message;
+            }
+            if (typeof nestedError === 'object' && nestedError !== null) {
+                const nestedMessage = 'message' in nestedError && typeof nestedError.message === 'string'
+                    ? nestedError.message.trim()
+                    : '';
+                if (nestedMessage) {
+                    return nestedMessage;
+                }
+            }
+            const serialized = JSON.stringify(error);
+            if (serialized && serialized !== '{}') {
+                return serialized;
+            }
+        }
+        return String(error);
+    }
+    normalizeConnectError(error, target, endpointOrOptions) {
+        const message = this.getUnknownErrorMessage(error);
+        if (this.isAutoConnectRequest(endpointOrOptions) && /ECONNREFUSED/i.test(message)) {
+            return new Error(`Failed to connect to existing browser: ${message}. ` +
+                `Chrome is not currently listening at ${target}. ` +
+                'DevToolsActivePort may be stale after a browser restart. ' +
+                'Re-open Chrome, confirm remote debugging is enabled at chrome://inspect/#remote-debugging, click Allow if prompted, and retry.');
+        }
+        return error instanceof Error
+            ? error
+            : new Error(`Failed to connect to existing browser: ${message}`);
+    }
+    buildConnectTimeoutError(target, endpointOrOptions) {
+        const baseMessage = `Timed out after ${this.CONNECT_TIMEOUT_MS}ms while connecting to existing browser: ${target}. ` +
+            'The CDP handshake did not complete in time.';
+        if (this.isAutoConnectRequest(endpointOrOptions)) {
+            return new Error(`${baseMessage} If Chrome prompted for remote debugging approval, click Allow in Chrome and then retry the tool call.`);
+        }
+        return new Error(`${baseMessage} Verify that the browser debugging endpoint is reachable and retry.`);
+    }
+    async connectWithTimeout(connectOptions, target, endpointOrOptions) {
+        const attemptId = ++this.connectAttemptId;
+        return await new Promise((resolve, reject) => {
+            let settled = false;
+            const timer = setTimeout(() => {
+                settled = true;
+                if (this.connectAttemptId === attemptId) {
+                    this.connectAttemptId += 1;
+                }
+                reject(this.buildConnectTimeoutError(target, endpointOrOptions));
+            }, this.CONNECT_TIMEOUT_MS);
+            void puppeteer
+                .connect(connectOptions)
+                .then(async (browser) => {
+                if (settled || this.connectAttemptId !== attemptId) {
+                    try {
+                        await browser.disconnect();
+                    }
+                    catch {
+                    }
+                    return;
+                }
+                settled = true;
+                clearTimeout(timer);
+                resolve(browser);
+            })
+                .catch((error) => {
+                if (settled || this.connectAttemptId !== attemptId) {
+                    return;
+                }
+                settled = true;
+                clearTimeout(timer);
+                reject(this.normalizeConnectError(error, target, endpointOrOptions));
+            });
+        });
+    }
+    async connect(endpointOrOptions) {
         this.explicitlyClosed = false;
         if (this.browser) {
             try {
@@ -358,15 +603,18 @@ export class CodeCollector {
             this.currentHeadless = null;
         }
         this.activePageIndex = null;
-        logger.info(`Connecting to existing browser: ${endpoint}`);
-        const connectOptions = endpoint.startsWith('ws://') || endpoint.startsWith('wss://')
-            ? { browserWSEndpoint: endpoint }
-            : { browserURL: endpoint };
-        this.browser = await puppeteer.connect(connectOptions);
+        const connectOptions = await this.resolveConnectOptions(endpointOrOptions);
+        const target = connectOptions.browserWSEndpoint ??
+            connectOptions.browserURL ??
+            'auto-detected Chrome debugging endpoint';
+        logger.info(`Connecting to existing browser: ${target}`);
+        this.browser = await this.connectWithTimeout(connectOptions, target, endpointOrOptions);
+        this.connectedToExistingBrowser = true;
         this.browser.on('disconnected', () => {
             logger.warn('Browser disconnected');
             this.browser = null;
             this.currentHeadless = null;
+            this.connectedToExistingBrowser = false;
             if (this.cdpSession) {
                 this.cdpSession = null;
                 this.cdpListeners = {};

package/dist/src/modules/process/MacProcessManager.js

@@ -103,31 +103,31 @@ export class MacProcessManager {
             if (!process) {
                 return [];
             }
-            const appleScript = `
-        tell application "System Events"
-          set processList to {}
-          try
-            set targetProcess to first process whose unix id is ${pid}
-            set procName to name of targetProcess
-            set windowList to {}
-
-            tell targetProcess
-              repeat with win in windows
-                set winInfo to {|
-                  title:name of win,
-                  className:procName,
-                  processId:${pid},
-                  handle:"applescript-window"
-                |}
-                set end of windowList to winInfo
-              end repeat
-            end tell
-
-            return windowList
-          on error
-            return {}
-          end try
-        end tell
+            const appleScript = `
+        tell application "System Events"
+          set processList to {}
+          try
+            set targetProcess to first process whose unix id is ${pid}
+            set procName to name of targetProcess
+            set windowList to {}
+
+            tell targetProcess
+              repeat with win in windows
+                set winInfo to {|
+                  title:name of win,
+                  className:procName,
+                  processId:${pid},
+                  handle:"applescript-window"
+                |}
+                set end of windowList to winInfo
+              end repeat
+            end tell
+
+            return windowList
+          on error
+            return {}
+          end try
+        end tell
       `;
             const { stdout } = await execAsync(`osascript -e '${appleScript.replace(/'/g, "'\"'\"'")}' 2>/dev/null || echo "[]"`, { timeout: 5000 });
             const windows = [];

package/dist/src/modules/process/memory/availability.js

@@ -103,55 +103,55 @@ export async function checkDebugPort(platform, pid) {
         return { success: false, error: 'Debug port check currently only implemented for Windows' };
     }
     try {
-        const psScript = `
-Add-Type @"
-using System;
-using System.Runtime.InteropServices;
-using System.ComponentModel;
-
-public class DebugChecker {
-    [DllImport("ntdll.dll")]
-    public static extern int NtQueryInformationProcess(IntPtr processHandle, int processInformationClass, out IntPtr processInformation, int processInformationLength, out int returnLength);
-
-    [DllImport("kernel32.dll", SetLastError = true)]
-    public static extern IntPtr OpenProcess(int access, bool inherit, int pid);
-
-    [DllImport("kernel32.dll", SetLastError = true)]
-    public static extern bool CloseHandle(IntPtr handle);
-
-    const int PROCESS_QUERY_INFORMATION = 0x0400;
-    const int ProcessDebugPort = 7;
-
-    public static object Check(int pid) {
-        IntPtr hProcess = OpenProcess(PROCESS_QUERY_INFORMATION, false, pid);
-        if (hProcess == IntPtr.Zero) {
-            int error = Marshal.GetLastWin32Error();
-            throw new Win32Exception(error, "Failed to open process");
-        }
-
-        try {
-            IntPtr debugPort;
-            int returnLength;
-            int status = NtQueryInformationProcess(hProcess, ProcessDebugPort, out debugPort, IntPtr.Size, out returnLength);
-
-            if (status != 0) {
-                return new { success = false, error = "NtQueryInformationProcess failed with status: 0x" + status.ToString("X") };
-            }
-
-            return new { success = true, isDebugged = debugPort != IntPtr.Zero };
-        } finally {
-            CloseHandle(hProcess);
-        }
-    }
-}
-"@
-
-try {
-    $result = [DebugChecker]::Check(${pid})
-    $result | ConvertTo-Json -Compress
-} catch {
-    @{ success = $false; error = $_.Exception.Message } | ConvertTo-Json -Compress
-}
+        const psScript = `
+Add-Type @"
+using System;
+using System.Runtime.InteropServices;
+using System.ComponentModel;
+
+public class DebugChecker {
+    [DllImport("ntdll.dll")]
+    public static extern int NtQueryInformationProcess(IntPtr processHandle, int processInformationClass, out IntPtr processInformation, int processInformationLength, out int returnLength);
+
+    [DllImport("kernel32.dll", SetLastError = true)]
+    public static extern IntPtr OpenProcess(int access, bool inherit, int pid);
+
+    [DllImport("kernel32.dll", SetLastError = true)]
+    public static extern bool CloseHandle(IntPtr handle);
+
+    const int PROCESS_QUERY_INFORMATION = 0x0400;
+    const int ProcessDebugPort = 7;
+
+    public static object Check(int pid) {
+        IntPtr hProcess = OpenProcess(PROCESS_QUERY_INFORMATION, false, pid);
+        if (hProcess == IntPtr.Zero) {
+            int error = Marshal.GetLastWin32Error();
+            throw new Win32Exception(error, "Failed to open process");
+        }
+
+        try {
+            IntPtr debugPort;
+            int returnLength;
+            int status = NtQueryInformationProcess(hProcess, ProcessDebugPort, out debugPort, IntPtr.Size, out returnLength);
+
+            if (status != 0) {
+                return new { success = false, error = "NtQueryInformationProcess failed with status: 0x" + status.ToString("X") };
+            }
+
+            return new { success = true, isDebugged = debugPort != IntPtr.Zero };
+        } finally {
+            CloseHandle(hProcess);
+        }
+    }
+}
+"@
+
+try {
+    $result = [DebugChecker]::Check(${pid})
+    $result | ConvertTo-Json -Compress
+} catch {
+    @{ success = $false; error = $_.Exception.Message } | ConvertTo-Json -Compress
+}
     `;
         const { stdout } = await executePowerShellScript(psScript, { maxBuffer: 1024 * 1024, timeout: 10000 });
         const _trimmed = stdout.trim();