@jshookmcp/jshook 0.2.7 → 0.2.9

package/dist/PageController-Bqm2kZ_X.mjs

@@ -0,0 +1,417 @@
+import { t as logger } from "./logger-Dh_xb7_2.mjs";
+import { Kt as PAGE_FRAME_SELECTOR_TIMEOUT_MS, qt as PAGE_NETWORK_IDLE_TIMEOUT_MS } from "./constants-B0OANIBL.mjs";
+import { setTimeout as setTimeout$1 } from "node:timers/promises";
+//#region src/modules/collector/PageController.ts
+var PageController = class {
+	constructor(collector) {
+		this.collector = collector;
+	}
+	hasAttachedTargetSession() {
+		return this.collector.getAttachedTargetSession() !== null;
+	}
+	getAttachedTargetInfo() {
+		return this.collector.getAttachedTargetInfo();
+	}
+	async evaluateAttachedTarget(code, options) {
+		return await this.collector.getBrowserTargetSessionManager().evaluate(code, options);
+	}
+	async addScriptToAttachedTarget(source) {
+		return await this.collector.getBrowserTargetSessionManager().addScriptToEvaluateOnNewDocument(source);
+	}
+	async navigate(url, options) {
+		const page = await this.collector.getActivePage();
+		const startTime = Date.now();
+		await page.goto(url, {
+			waitUntil: options?.waitUntil || "networkidle2",
+			timeout: options?.timeout || 3e4
+		});
+		const loadTime = Date.now() - startTime;
+		const title = await page.title();
+		const currentUrl = page.url();
+		logger.info(`Navigated to: ${url}`);
+		return {
+			url: currentUrl,
+			title,
+			loadTime
+		};
+	}
+	async reload(options) {
+		await (await this.collector.getActivePage()).reload({
+			waitUntil: options?.waitUntil || "networkidle2",
+			timeout: options?.timeout || 3e4
+		});
+		logger.info("Page reloaded");
+	}
+	async goBack(timeout = 1e4) {
+		await (await this.collector.getActivePage()).goBack({
+			waitUntil: "domcontentloaded",
+			timeout
+		});
+		logger.info("Navigated back");
+	}
+	async goForward(timeout = 1e4) {
+		await (await this.collector.getActivePage()).goForward({
+			waitUntil: "domcontentloaded",
+			timeout
+		});
+		logger.info("Navigated forward");
+	}
+	async click(selector, options, frameOptions) {
+		const page = await this.collector.getActivePage();
+		await (await this.resolveFrame(page, frameOptions)).click(selector, {
+			button: options?.button || "left",
+			clickCount: options?.clickCount || 1,
+			delay: options?.delay
+		});
+		logger.info(`Clicked: ${selector}${frameOptions?.frameUrl || frameOptions?.frameSelector ? " (in frame)" : ""}`);
+	}
+	async type(selector, text, options, frameOptions) {
+		const page = await this.collector.getActivePage();
+		await (await this.resolveFrame(page, frameOptions)).type(selector, text, { delay: options?.delay });
+		logger.info(`Typed into ${selector}: ${text.substring(0, 20)}...`);
+	}
+	async select(selector, values, frameOptions) {
+		const page = await this.collector.getActivePage();
+		await (await this.resolveFrame(page, frameOptions)).select(selector, ...values);
+		logger.info(`Selected in ${selector}: ${values.join(", ")}`);
+	}
+	async hover(selector, frameOptions) {
+		const page = await this.collector.getActivePage();
+		await (await this.resolveFrame(page, frameOptions)).hover(selector);
+		logger.info(`Hovered: ${selector}`);
+	}
+	async scroll(options) {
+		await (await this.collector.getActivePage()).evaluate((opts) => {
+			window.scrollTo(opts.x || 0, opts.y || 0);
+		}, options);
+		logger.info(`Scrolled to: x=${options.x || 0}, y=${options.y || 0}`);
+	}
+	async waitForSelector(selector, timeout) {
+		try {
+			const page = await this.collector.getActivePage();
+			await page.waitForSelector(selector, { timeout: timeout || 3e4 });
+			const element = await page.evaluate((sel) => {
+				const el = document.querySelector(sel);
+				if (!el) return null;
+				return {
+					tagName: el.tagName.toLowerCase(),
+					id: el.id || void 0,
+					className: el.className || void 0,
+					textContent: el.textContent?.trim().substring(0, 100) || void 0,
+					attributes: Array.from(el.attributes).reduce((acc, attr) => {
+						acc[attr.name] = attr.value;
+						return acc;
+					}, {})
+				};
+			}, selector);
+			logger.info(`Selector appeared: ${selector}`);
+			return {
+				success: true,
+				element,
+				message: `Selector appeared: ${selector}`
+			};
+		} catch (error) {
+			logger.error(`waitForSelector timeout for ${selector}:`, error);
+			return {
+				success: false,
+				message: `Timeout waiting for selector: ${selector}`
+			};
+		}
+	}
+	async waitForNavigation(timeout) {
+		await (await this.collector.getActivePage()).waitForNavigation({
+			waitUntil: "networkidle2",
+			timeout: timeout || 3e4
+		});
+		logger.info("Navigation completed");
+	}
+	async evaluate(code, frameOptions) {
+		const page = await this.collector.getActivePage();
+		if (frameOptions?.frameUrl || frameOptions?.frameSelector) {
+			const result = await evaluateOnContextWithTimeout(page, await this.resolveFrame(page, frameOptions), code);
+			logger.info("JavaScript executed (in frame)");
+			return result;
+		}
+		const result = await evaluateWithTimeout(page, code);
+		logger.info("JavaScript executed");
+		return result;
+	}
+	/**
+	* Resolve a child frame from the active page.
+	* When no options are provided (or both fields are undefined), returns page.mainFrame().
+	*/
+	async resolveFrame(page, options) {
+		if (!options) return page.mainFrame();
+		if (options.frameUrl) {
+			const frames = page.frames();
+			const frame = frames.find((f) => f.url().includes(options.frameUrl));
+			if (!frame) {
+				const available = frames.map((f) => f.url()).filter((u) => u && u !== "about:blank");
+				throw new Error(`No frame matching URL substring "${options.frameUrl}". Available frames: ${available.join(", ") || "(none)"}`);
+			}
+			return frame;
+		}
+		if (options.frameSelector) {
+			await page.waitForSelector(options.frameSelector, { timeout: PAGE_FRAME_SELECTOR_TIMEOUT_MS }).catch(() => null);
+			const handle = await page.$(options.frameSelector);
+			if (!handle) throw new Error(`No element found for iframe selector: ${options.frameSelector}`);
+			const frame = await handle.contentFrame();
+			if (!frame) throw new Error(`Element "${options.frameSelector}" exists but has no content frame (not an iframe or not yet loaded).`);
+			return frame;
+		}
+		return page.mainFrame();
+	}
+	/** List all frames in the active page with URL and name info. */
+	async listFrames() {
+		const page = await this.collector.getActivePage();
+		const mainFrame = page.mainFrame();
+		return page.frames().map((frame) => ({
+			url: frame.url(),
+			name: frame.name() || "",
+			id: frame._id || "",
+			isMainFrame: frame === mainFrame
+		}));
+	}
+	async getURL() {
+		return (await this.collector.getActivePage()).url();
+	}
+	async getTitle() {
+		return await (await this.collector.getActivePage()).title();
+	}
+	async getContent() {
+		return await (await this.collector.getActivePage()).content();
+	}
+	async screenshot(options) {
+		const page = await this.collector.getActivePage();
+		const screenshotOpts = {
+			path: options?.path,
+			type: options?.type || "png",
+			quality: options?.quality,
+			fullPage: options?.fullPage || false
+		};
+		if (options?.clip) {
+			screenshotOpts.clip = options.clip;
+			screenshotOpts.fullPage = false;
+		}
+		const buffer = await page.screenshot(screenshotOpts);
+		logger.info(`Screenshot taken${options?.path ? `: ${options.path}` : ""}`);
+		return buffer;
+	}
+	async getPerformanceMetrics() {
+		const metrics = await evaluateWithTimeout(await this.collector.getActivePage(), () => {
+			const perf = performance.getEntriesByType("navigation")[0];
+			return {
+				domContentLoaded: perf.domContentLoadedEventEnd - perf.domContentLoadedEventStart,
+				loadComplete: perf.loadEventEnd - perf.loadEventStart,
+				dns: perf.domainLookupEnd - perf.domainLookupStart,
+				tcp: perf.connectEnd - perf.connectStart,
+				request: perf.responseStart - perf.requestStart,
+				response: perf.responseEnd - perf.responseStart,
+				total: perf.loadEventEnd - perf.fetchStart,
+				resources: performance.getEntriesByType("resource").length
+			};
+		});
+		logger.info("Performance metrics retrieved");
+		return metrics;
+	}
+	async injectScript(scriptContent) {
+		await evaluateWithTimeout(await this.collector.getActivePage(), (script) => {
+			const scriptElement = document.createElement("script");
+			scriptElement.textContent = script;
+			document.head.appendChild(scriptElement);
+		}, scriptContent);
+		logger.info("Script injected into page");
+	}
+	async setCookies(cookies) {
+		await (await this.collector.getActivePage()).setCookie(...cookies);
+		logger.info(`Set ${cookies.length} cookies`);
+	}
+	async getCookies() {
+		const cookies = await (await this.collector.getActivePage()).cookies();
+		logger.info(`Retrieved ${cookies.length} cookies`);
+		return cookies;
+	}
+	async clearCookies() {
+		const page = await this.collector.getActivePage();
+		const cookies = await page.cookies();
+		await page.deleteCookie(...cookies);
+		logger.info("All cookies cleared");
+	}
+	async setViewport(width, height) {
+		await (await this.collector.getActivePage()).setViewport({
+			width,
+			height
+		});
+		logger.info(`Viewport set to ${width}x${height}`);
+	}
+	async emulateDevice(deviceName) {
+		const page = await this.collector.getActivePage();
+		const devices = {
+			iPhone: {
+				viewport: {
+					width: 375,
+					height: 812,
+					isMobile: true
+				},
+				userAgent: "Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X) AppleWebKit/605.1.15"
+			},
+			iPad: {
+				viewport: {
+					width: 768,
+					height: 1024,
+					isMobile: true
+				},
+				userAgent: "Mozilla/5.0 (iPad; CPU OS 14_0 like Mac OS X) AppleWebKit/605.1.15"
+			},
+			Android: {
+				viewport: {
+					width: 360,
+					height: 640,
+					isMobile: true
+				},
+				userAgent: "Mozilla/5.0 (Linux; Android 10) AppleWebKit/537.36 Chrome/91.0.4472.120"
+			}
+		};
+		const normalized = String(deviceName || "").trim().toLowerCase();
+		let resolvedDevice = null;
+		if (normalized.includes("iphone")) resolvedDevice = "iPhone";
+		else if (normalized.includes("ipad")) resolvedDevice = "iPad";
+		else if (normalized.includes("android") || normalized.includes("pixel")) resolvedDevice = "Android";
+		if (!resolvedDevice) throw new Error(`Unsupported device "${deviceName}". Supported values include: iPhone, iPad, Android (aliases like "iPhone 13" are accepted).`);
+		const device = devices[resolvedDevice];
+		await page.setViewport(device.viewport);
+		await page.setUserAgent(device.userAgent);
+		logger.info(`Emulating ${resolvedDevice} (input: ${deviceName})`);
+		return resolvedDevice;
+	}
+	async waitForNetworkIdle(timeout = PAGE_NETWORK_IDLE_TIMEOUT_MS) {
+		await (await this.collector.getActivePage()).waitForNetworkIdle({ timeout });
+		logger.info("Network is idle");
+	}
+	async getLocalStorage() {
+		const storage = await (await this.collector.getActivePage()).evaluate(() => {
+			const items = {};
+			for (let i = 0; i < localStorage.length; i++) {
+				const key = localStorage.key(i);
+				if (key) items[key] = localStorage.getItem(key) || "";
+			}
+			return items;
+		});
+		logger.info(`Retrieved ${Object.keys(storage).length} localStorage items`);
+		return storage;
+	}
+	async setLocalStorage(key, value) {
+		await (await this.collector.getActivePage()).evaluate((k, v) => {
+			localStorage.setItem(k, v);
+		}, key, value);
+		logger.info(`Set localStorage: ${key}`);
+	}
+	async clearLocalStorage() {
+		await (await this.collector.getActivePage()).evaluate(() => {
+			localStorage.clear();
+		});
+		logger.info("LocalStorage cleared");
+	}
+	async pressKey(key) {
+		await (await this.collector.getActivePage()).keyboard.press(key);
+		logger.info(`Pressed key: ${key}`);
+	}
+	async uploadFile(selector, filePath) {
+		const input = await (await this.collector.getActivePage()).$(selector);
+		if (!input) throw new Error(`File input not found: ${selector}`);
+		await input.uploadFile(filePath);
+		logger.info(`File uploaded: ${filePath}`);
+	}
+	async getAllLinks() {
+		const links = await (await this.collector.getActivePage()).evaluate(() => {
+			const anchors = document.querySelectorAll("a[href]");
+			const result = [];
+			for (let i = 0; i < anchors.length; i++) {
+				const anchor = anchors[i];
+				result.push({
+					text: anchor.textContent?.trim() || "",
+					href: anchor.href
+				});
+			}
+			return result;
+		});
+		logger.info(`Found ${links.length} links`);
+		return links;
+	}
+	async getPage() {
+		return await this.collector.getActivePage();
+	}
+};
+/**
+* Pre-flight CDP health check: verify the page CDP target is responsive.
+* After debugger enable + pause/resume, the Playwright CDP session can enter
+* a zombie state where Runtime.evaluate hangs indefinitely without firing
+* 'disconnected'. Without this check, page.evaluate() blocks for the full 30 s
+* timeout — with this check we fail fast (~3 s) with a clear message.
+*/
+async function checkPageCDPHealth(page, timeoutMs = 500) {
+	const ac = new AbortController();
+	const timer = setTimeout$1(timeoutMs, void 0, { signal: ac.signal }).then(() => {
+		throw new Error("cdp_unreachable");
+	});
+	try {
+		const cdp = await Promise.race([page.createCDPSession(), timer]);
+		await Promise.race([cdp.send("Runtime.evaluate", {
+			expression: "1",
+			returnByValue: true
+		}), timer]);
+	} catch (err) {
+		if ((err instanceof Error ? err.message : String(err)) === "cdp_unreachable") throw new Error("CDP session unresponsive — the debugger may be blocking page evaluation. Call debugger_lifecycle({ action: 'disable' })() before this tool, or run it before debugger_lifecycle({ action: 'enable' })().", { cause: err });
+		throw err;
+	} finally {
+		ac.abort();
+	}
+}
+async function evaluateOnContextWithTimeout(page, context, pageFunction, ...args) {
+	const timeoutMs = 3e4;
+	await checkPageCDPHealth(page);
+	return Promise.race([context.evaluate(pageFunction, ...[...args]), new Promise((_, reject) => setTimeout(() => reject(/* @__PURE__ */ new Error(`page.evaluate timed out after ${timeoutMs}ms`)), timeoutMs))]);
+}
+async function evaluateWithTimeout(page, pageFunction, ...args) {
+	return evaluateOnContextWithTimeout(page, page, pageFunction, ...args);
+}
+/**
+* Wrap a page.evaluateOnNewDocument() call with:
+* 1. A CDP pre-flight health check
+* 2. A hard timeout (30 s) as a backstop
+*/
+async function evaluateOnNewDocumentWithTimeout(page, pageFunction, ...args) {
+	const timeoutMs = 3e4;
+	await checkPageCDPHealth(page);
+	return Promise.race([page.evaluateOnNewDocument(pageFunction, ...[...args]), new Promise((_, reject) => setTimeout(() => reject(/* @__PURE__ */ new Error(`page.evaluateOnNewDocument timed out after ${timeoutMs}ms`)), timeoutMs))]);
+}
+/**
+* Wrap page.coverage.startJSCoverage() with a timeout.
+*/
+async function coverageStartJSWithTimeout(page, options) {
+	const timeoutMs = 3e4;
+	return Promise.race([page.coverage.startJSCoverage(options), new Promise((_, reject) => setTimeout(() => reject(/* @__PURE__ */ new Error(`coverage.startJSCoverage timed out after ${timeoutMs}ms`)), timeoutMs))]);
+}
+/**
+* Wrap page.coverage.startCSSCoverage() with a timeout.
+*/
+async function coverageStartCSSWithTimeout(page, options) {
+	const timeoutMs = 3e4;
+	return Promise.race([page.coverage.startCSSCoverage(options), new Promise((_, reject) => setTimeout(() => reject(/* @__PURE__ */ new Error(`coverage.startCSSCoverage timed out after ${timeoutMs}ms`)), timeoutMs))]);
+}
+/**
+* Wrap page.coverage.stopJSCoverage() with a timeout.
+*/
+async function coverageStopJSWithTimeout(page) {
+	const timeoutMs = 3e4;
+	return Promise.race([page.coverage.stopJSCoverage(), new Promise((_, reject) => setTimeout(() => reject(/* @__PURE__ */ new Error(`coverage.stopJSCoverage timed out after ${timeoutMs}ms`)), timeoutMs))]);
+}
+/**
+* Wrap page.coverage.stopCSSCoverage() with a timeout.
+*/
+async function coverageStopCSSWithTimeout(page) {
+	const timeoutMs = 3e4;
+	return Promise.race([page.coverage.stopCSSCoverage(), new Promise((_, reject) => setTimeout(() => reject(/* @__PURE__ */ new Error(`coverage.stopCSSCoverage timed out after ${timeoutMs}ms`)), timeoutMs))]);
+}
+//#endregion
+export { coverageStopJSWithTimeout as a, coverageStopCSSWithTimeout as i, coverageStartCSSWithTimeout as n, evaluateOnNewDocumentWithTimeout as o, coverageStartJSWithTimeout as r, evaluateWithTimeout as s, PageController as t };

package/dist/{PointerChainEngine-Cd73qu5b.mjs → PointerChainEngine-BOhyVsjx.mjs}

@@ -1,7 +1,7 @@
-import { Dt as POINTER_CHAIN_SCAN_CHUNK_SIZE, Et as POINTER_CHAIN_MAX_RESULTS, Tt as POINTER_CHAIN_MAX_OFFSET, wt as POINTER_CHAIN_MAX_DEPTH } from "./constants-CCvsN80K.mjs";
-import { t as nativeMemoryManager } from "./NativeMemoryManager.impl-CB6gJ0NM.mjs";
-import { t as createPlatformProvider } from "./factory-CibqTNC8.mjs";
-import { n as parseAddress, t as formatAddress } from "./formatAddress-ChCSIRWT.mjs";
+import { Jt as POINTER_CHAIN_MAX_DEPTH, Xt as POINTER_CHAIN_MAX_RESULTS, Yt as POINTER_CHAIN_MAX_OFFSET, Zt as POINTER_CHAIN_SCAN_CHUNK_SIZE } from "./constants-B0OANIBL.mjs";
+import { t as createPlatformProvider } from "./factory-DxlGh9Xf.mjs";
+import { t as nativeMemoryManager } from "./NativeMemoryManager.impl-dZtA1ZGn.mjs";
+import { n as parseAddress, t as formatAddress } from "./formatAddress-DVkj9kpI.mjs";
 import { randomUUID } from "node:crypto";
 //#region src/native/PointerChainEngine.ts
 /**

package/dist/PrerequisiteError-Dl33Svkz.mjs

@@ -0,0 +1,20 @@
+import { t as ToolError } from "./ToolError-jh9whhMd.mjs";
+//#region src/errors/PrerequisiteError.ts
+/**
+* Thrown when a tool's prerequisite is not met (e.g. debugger not enabled,
+* browser not connected, profiling not started).
+*
+* The MCP server catches this and returns a graceful
+* `{ success: false, message }` response instead of `isError: true`.
+*
+* Extends ToolError with code 'PREREQUISITE' for unified error classification.
+* Constructor signature unchanged — backward-compatible with all existing callers.
+*/
+var PrerequisiteError = class extends ToolError {
+	constructor(message) {
+		super("PREREQUISITE", message);
+		this.name = "PrerequisiteError";
+	}
+};
+//#endregion
+export { PrerequisiteError as t };

package/dist/ResponseBuilder-D3iFYx2N.mjs

@@ -0,0 +1,143 @@
+//#region src/server/domains/shared/ResponseBuilder.ts
+/**
+* Fluent builder for MCP tool responses.
+*
+* Replaces the verbose 14-line deep-nesting pattern:
+* ```
+* return { content: [{ type: 'text', text: JSON.stringify({...}, null, 2) }] };
+* ```
+*
+* With a chainable API:
+* ```
+* return R.ok().set('driver', 'chrome').json();
+* ```
+*/
+var ResponseBuilder = class {
+	payload = {};
+	_isError = false;
+	_additionalContent = [];
+	_useStructured = false;
+	/** Mark as success (sets `success: true`). */
+	ok() {
+		this.payload.success = true;
+		return this;
+	}
+	/** Mark as failure (sets `success: false, error: <message>, message: <message>`). */
+	fail(error) {
+		this.payload.success = false;
+		const msg = error instanceof Error ? error.message : String(error);
+		this.payload.error = msg;
+		this.payload.message = msg;
+		return this;
+	}
+	/** Set a single key-value pair. */
+	set(key, value) {
+		this.payload[key] = value;
+		return this;
+	}
+	/** Merge multiple fields at once. */
+	merge(fields) {
+		Object.assign(this.payload, fields);
+		return this;
+	}
+	/** Set MCP-level `isError: true` on the response envelope. */
+	mcpError() {
+		this._isError = true;
+		return this;
+	}
+	/** Push an image block to the final response. */
+	image(base64, mimeType) {
+		this._additionalContent.push({
+			type: "image",
+			data: base64,
+			mimeType
+		});
+		return this;
+	}
+	/** Push an embedded resource block to the final response. */
+	embeddedResource(uri, text, mimeType = "text/plain") {
+		this._additionalContent.push({
+			type: "resource",
+			resource: {
+				uri,
+				text,
+				mimeType
+			}
+		});
+		return this;
+	}
+	/** Send output payload natively as `structuredContent` in the MCP envelope instead of stringifying inside text block. */
+	structured() {
+		this._useStructured = true;
+		return this;
+	}
+	/**
+	* Build the ToolResponse. Handles text vs structured plus extra blocks.
+	* Optionally merges extra fields before building.
+	*/
+	json(fields) {
+		if (fields) this.merge(fields);
+		return {
+			content: [{
+				type: "text",
+				text: JSON.stringify(this.payload, null, 2)
+			}, ...this._additionalContent],
+			...this._isError ? { isError: true } : {},
+			...this._useStructured ? { structuredContent: this.payload } : {}
+		};
+	}
+	/** Alias for json(). */
+	build(fields) {
+		return this.json(fields);
+	}
+	/** Build a ToolResponse from an arbitrary value (no success/error wrapper). */
+	static raw(data) {
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(data, null, 2)
+		}] };
+	}
+	/**
+	* Build a ToolResponse from a plain text string.
+	* Setting `isError = true` returns a soft error for macro compatibility
+	* without triggering a JSON-RPC ErrorCode.
+	*/
+	static text(text, isError = false) {
+		return {
+			content: [{
+				type: "text",
+				text
+			}],
+			...isError ? { isError: true } : {}
+		};
+	}
+	/**
+	* Safely extract and parse JSON from an MCP ToolResponse.
+	* Useful for consuming tool results in workflow/orchestration logic.
+	*/
+	static parse(response) {
+		if (!response.content || response.content.length === 0) throw new Error("ToolResponse has no content");
+		const textBlock = response.content.find((c) => c.type === "text");
+		if (!textBlock || !("text" in textBlock)) throw new Error("ToolResponse has no text content block");
+		try {
+			return JSON.parse(textBlock.text);
+		} catch (e) {
+			throw new Error(`Failed to parse tool result as JSON: ${String(e)}\nRaw text: ${textBlock.text.substring(0, 500)}`, { cause: e });
+		}
+	}
+};
+/** Shorthand factory — the primary entry point for building responses. */
+const R = {
+	/** Start a success response (`{ success: true, ... }`). */
+	ok: () => new ResponseBuilder().ok(),
+	/** Start a failure response (`{ success: false, error: "..." }`). */
+	fail: (error) => new ResponseBuilder().fail(error),
+	/** Wrap an existing object as-is (no success/error wrapper). */
+	raw: (data) => ResponseBuilder.raw(data),
+	/** Wrap a plain text string. */
+	text: (text, isError = false) => ResponseBuilder.text(text, isError),
+	/** Parse a response back into an object. */
+	parse: (response) => ResponseBuilder.parse(response)
+};
+//#endregion
+export { R as t };