@jshookmcp/jshook 0.2.8 → 0.2.9

package/dist/handlers-DdFzXLvF.mjs

@@ -0,0 +1,446 @@
+import { i as resolveArtifactPath } from "./artifacts-Bk2-_uPq.mjs";
+import { t as TraceDB } from "./TraceRecorder-DgxyVbdQ.mjs";
+import { n as argEnum } from "./parse-args-BlRjqlkL.mjs";
+import { writeFile } from "node:fs/promises";
+//#region src/server/domains/trace/TraceSummarizer.ts
+/**
+* Summarize trace events at the specified detail level.
+*/
+function summarizeEvents(events, detail = "balanced") {
+	if (events.length === 0) return {
+		detail,
+		totalEvents: 0,
+		timeRange: {
+			start: 0,
+			end: 0,
+			durationMs: 0
+		},
+		categories: [],
+		keyMoments: detail !== "compact" ? [] : void 0
+	};
+	const timestamps = events.map((e) => e.timestamp);
+	const start = Math.min(...timestamps);
+	const end = Math.max(...timestamps);
+	const catMap = /* @__PURE__ */ new Map();
+	for (const event of events) {
+		let cat = catMap.get(event.category);
+		if (!cat) {
+			cat = {
+				count: 0,
+				first: event.timestamp,
+				last: event.timestamp,
+				types: /* @__PURE__ */ new Map()
+			};
+			catMap.set(event.category, cat);
+		}
+		cat.count++;
+		cat.first = Math.min(cat.first, event.timestamp);
+		cat.last = Math.max(cat.last, event.timestamp);
+		cat.types.set(event.eventType, (cat.types.get(event.eventType) ?? 0) + 1);
+	}
+	const categories = [...catMap.entries()].toSorted((a, b) => b[1].count - a[1].count).map(([category, info]) => ({
+		category,
+		count: info.count,
+		firstTimestamp: info.first,
+		lastTimestamp: info.last,
+		topEventTypes: [...info.types.entries()].toSorted((a, b) => b[1] - a[1]).slice(0, 5).map(([type, count]) => ({
+			type,
+			count
+		}))
+	}));
+	const summary = {
+		detail,
+		totalEvents: events.length,
+		timeRange: {
+			start,
+			end,
+			durationMs: end - start
+		},
+		categories
+	};
+	if (detail === "balanced" || detail === "full") summary.keyMoments = extractKeyMoments(events);
+	return summary;
+}
+/**
+* Extract key moments from a trace event stream.
+*
+* Identifies:
+* - Debugger pauses (breakpoint hits)
+* - Network request completions
+* - Runtime exceptions
+* - Page navigations
+*/
+function extractKeyMoments(events) {
+	const moments = [];
+	for (const event of events) if (event.eventType === "Debugger.paused") moments.push({
+		timestamp: event.timestamp,
+		type: "breakpoint",
+		description: `Debugger paused${event.scriptId ? ` at script ${event.scriptId}` : ""}${event.lineNumber ? `:${event.lineNumber}` : ""}`,
+		data: event.data
+	});
+	else if (event.eventType === "Network.loadingFinished") moments.push({
+		timestamp: event.timestamp,
+		type: "network_complete",
+		description: "Network request completed",
+		data: event.data
+	});
+	else if (event.eventType === "Runtime.exceptionThrown") moments.push({
+		timestamp: event.timestamp,
+		type: "exception",
+		description: "Runtime exception thrown",
+		data: event.data
+	});
+	else if (event.eventType === "Page.frameNavigated" || event.eventType === "Page.navigatedWithinDocument") moments.push({
+		timestamp: event.timestamp,
+		type: "navigation",
+		description: "Page navigation",
+		data: event.data
+	});
+	return moments;
+}
+/**
+* Summarize memory deltas, detecting anomalies.
+*
+* An anomaly is defined as an address that receives significantly more
+* writes than the average (> 3× the mean write count).
+*/
+function summarizeMemoryDeltas(deltas) {
+	if (deltas.length === 0) return {
+		totalDeltas: 0,
+		uniqueAddresses: 0,
+		anomalies: [],
+		topAddresses: []
+	};
+	const writeMap = /* @__PURE__ */ new Map();
+	for (const delta of deltas) writeMap.set(delta.address, (writeMap.get(delta.address) ?? 0) + 1);
+	const uniqueAddresses = writeMap.size;
+	const totalWrites = deltas.length;
+	const meanWrites = totalWrites / uniqueAddresses;
+	const sorted = [...writeMap.entries()].toSorted((a, b) => b[1] - a[1]);
+	const topAddresses = sorted.slice(0, 10).map(([address, writeCount]) => ({
+		address,
+		writeCount
+	}));
+	const anomalyThreshold = meanWrites * 3;
+	return {
+		totalDeltas: totalWrites,
+		uniqueAddresses,
+		anomalies: sorted.filter(([, count]) => count > anomalyThreshold).map(([address, writeCount]) => ({
+			address,
+			writeCount,
+			description: `${writeCount} writes (${(writeCount / meanWrites).toFixed(1)}× average)`
+		})),
+		topAddresses
+	};
+}
+//#endregion
+//#region src/server/domains/trace/handlers.ts
+/**
+* Trace domain tool handlers.
+*
+* Implements start/stop recording, SQL query, timestamp seek,
+* heap snapshot diffing, and Chrome Trace Event export.
+*/
+var TraceToolHandlers = class {
+	constructor(recorder, ctx) {
+		this.recorder = recorder;
+		this.ctx = ctx;
+	}
+	async handleTraceRecording(args) {
+		return argEnum(args, "action", new Set(["start", "stop"])) === "stop" ? this.handleStopTraceRecording() : this.handleStartTraceRecording(args);
+	}
+	async handleStartTraceRecording(args) {
+		const cdpDomains = args["cdpDomains"];
+		const recordMemoryDeltas = args["recordMemoryDeltas"];
+		const eventBus = this.ctx.eventBus;
+		if (!eventBus) throw new Error("EventBus not available on server context");
+		let cdpSession = null;
+		try {
+			if (this.ctx.collector) {
+				const pageAny = await this.ctx.collector.getActivePage();
+				if (typeof pageAny.createCDPSession === "function") cdpSession = await pageAny.createCDPSession();
+			}
+		} catch {}
+		const session = await this.recorder.start(eventBus, cdpSession, {
+			cdpDomains,
+			recordMemoryDeltas: recordMemoryDeltas ?? true
+		});
+		return {
+			status: "recording",
+			sessionId: session.sessionId,
+			dbPath: session.dbPath,
+			message: `Recording started. CDP session: ${cdpSession ? "active" : "not available"}`
+		};
+	}
+	async handleStopTraceRecording() {
+		const session = this.recorder.stop();
+		const duration = session.stoppedAt ? session.stoppedAt - session.startedAt : 0;
+		return {
+			status: "stopped",
+			sessionId: session.sessionId,
+			dbPath: session.dbPath,
+			eventCount: session.eventCount,
+			memoryDeltaCount: session.memoryDeltaCount,
+			heapSnapshotCount: session.heapSnapshotCount,
+			durationMs: duration,
+			message: `Recording stopped. ${session.eventCount} events, ${session.memoryDeltaCount} memory deltas, ${session.heapSnapshotCount} heap snapshots recorded.`
+		};
+	}
+	async handleQueryTraceSql(args) {
+		const sql = args["sql"];
+		const dbPath = args["dbPath"];
+		if (!sql) throw new Error("sql parameter is required");
+		let result;
+		let tempDb = null;
+		try {
+			if (dbPath) {
+				tempDb = new TraceDB({ dbPath });
+				result = tempDb.query(sql);
+			} else {
+				const activeDb = this.recorder.getDB();
+				if (!activeDb) throw new Error("GRACEFUL: No active recording and no dbPath specified. Start a recording or provide a dbPath.");
+				activeDb.flush();
+				result = activeDb.query(sql);
+			}
+			return {
+				columns: result.columns,
+				rows: result.rows,
+				rowCount: result.rowCount
+			};
+		} finally {
+			if (tempDb) tempDb.close();
+		}
+	}
+	async handleSeekToTimestamp(args) {
+		const timestamp = args["timestamp"];
+		const dbPath = args["dbPath"];
+		const windowMs = args["windowMs"] ?? 100;
+		if (!timestamp) throw new Error("timestamp parameter is required");
+		let tempDb = null;
+		try {
+			const db = this.getDbForReading(dbPath);
+			if (dbPath) tempDb = db;
+			const events = db.getEventsByTimeRange(timestamp - windowMs, timestamp + windowMs);
+			const debuggerEventsResult = db.query(`SELECT * FROM events WHERE category = 'debugger' AND timestamp <= ${timestamp} ORDER BY timestamp DESC LIMIT 5`);
+			const memoryStateResult = db.query(`SELECT m1.* FROM memory_deltas m1
+         INNER JOIN (SELECT address, MAX(timestamp) as max_ts FROM memory_deltas WHERE timestamp <= ${timestamp} GROUP BY address) m2
+         ON m1.address = m2.address AND m1.timestamp = m2.max_ts
+         ORDER BY m1.address`);
+			const networkResult = db.query(`SELECT * FROM events WHERE category = 'network' AND event_type = 'Network.loadingFinished' AND timestamp <= ${timestamp} ORDER BY timestamp DESC LIMIT 20`);
+			const snapshotResult = db.query(`SELECT id, timestamp, summary FROM heap_snapshots WHERE timestamp <= ${timestamp} ORDER BY timestamp DESC LIMIT 1`);
+			return {
+				seekTimestamp: timestamp,
+				windowMs,
+				events: events.map((e) => ({
+					timestamp: e.timestamp,
+					category: e.category,
+					eventType: e.eventType,
+					data: this.safeParseJSON(e.data),
+					scriptId: e.scriptId,
+					lineNumber: e.lineNumber
+				})),
+				debuggerState: { recentEvents: debuggerEventsResult.rows.map((row) => this.rowToObject(debuggerEventsResult.columns, row)) },
+				memoryState: { addressValues: memoryStateResult.rows.map((row) => this.rowToObject(memoryStateResult.columns, row)) },
+				networkState: { completedRequests: networkResult.rows.map((row) => this.rowToObject(networkResult.columns, row)) },
+				nearestHeapSnapshot: snapshotResult.rows.length > 0 ? this.rowToObject(snapshotResult.columns, snapshotResult.rows[0]) : null
+			};
+		} finally {
+			if (tempDb) tempDb.close();
+		}
+	}
+	async handleDiffHeapSnapshots(args) {
+		const snapshotId1 = args["snapshotId1"];
+		const snapshotId2 = args["snapshotId2"];
+		const dbPath = args["dbPath"];
+		if (!snapshotId1 || !snapshotId2) throw new Error("snapshotId1 and snapshotId2 are required");
+		let tempDb = null;
+		try {
+			const db = this.getDbForReading(dbPath);
+			if (dbPath) tempDb = db;
+			const snap1Result = db.query(`SELECT id, timestamp, summary FROM heap_snapshots WHERE id = ${snapshotId1}`);
+			const snap2Result = db.query(`SELECT id, timestamp, summary FROM heap_snapshots WHERE id = ${snapshotId2}`);
+			if (snap1Result.rowCount === 0) throw new Error(`Snapshot with id ${snapshotId1} not found`);
+			if (snap2Result.rowCount === 0) throw new Error(`Snapshot with id ${snapshotId2} not found`);
+			const snap1Row = this.rowToObject(snap1Result.columns, snap1Result.rows[0]);
+			const snap2Row = this.rowToObject(snap2Result.columns, snap2Result.rows[0]);
+			const summary1 = this.safeParseJSON(snap1Row["summary"]);
+			const summary2 = this.safeParseJSON(snap2Row["summary"]);
+			const counts1 = summary1["objectCounts"] ?? {};
+			const counts2 = summary2["objectCounts"] ?? {};
+			const allKeys = new Set([...Object.keys(counts1), ...Object.keys(counts2)]);
+			const added = [];
+			const removed = [];
+			const changed = [];
+			for (const key of allKeys) {
+				const c1 = counts1[key] ?? 0;
+				const c2 = counts2[key] ?? 0;
+				if (c1 === 0 && c2 > 0) added.push({
+					name: key,
+					count: c2
+				});
+				else if (c1 > 0 && c2 === 0) removed.push({
+					name: key,
+					count: c1
+				});
+				else if (c1 !== c2) changed.push({
+					name: key,
+					countBefore: c1,
+					countAfter: c2,
+					delta: c2 - c1
+				});
+			}
+			changed.sort((a, b) => Math.abs(b.delta) - Math.abs(a.delta));
+			const totalSize1 = summary1["totalSize"] ?? 0;
+			const totalSize2 = summary2["totalSize"] ?? 0;
+			return {
+				snapshot1: {
+					id: snap1Row["id"],
+					timestamp: snap1Row["timestamp"],
+					totalSize: totalSize1,
+					nodeCount: summary1["nodeCount"] ?? 0
+				},
+				snapshot2: {
+					id: snap2Row["id"],
+					timestamp: snap2Row["timestamp"],
+					totalSize: totalSize2,
+					nodeCount: summary2["nodeCount"] ?? 0
+				},
+				diff: {
+					added: added.slice(0, 50),
+					removed: removed.slice(0, 50),
+					changed: changed.slice(0, 100),
+					totalSizeDelta: totalSize2 - totalSize1,
+					addedCount: added.length,
+					removedCount: removed.length,
+					changedCount: changed.length
+				}
+			};
+		} finally {
+			if (tempDb) tempDb.close();
+		}
+	}
+	async handleExportTrace(args) {
+		const dbPath = args["dbPath"];
+		const outputPath = args["outputPath"];
+		let tempDb = null;
+		try {
+			const db = this.getDbForReading(dbPath);
+			if (dbPath) tempDb = db;
+			const allEvents = db.query("SELECT timestamp, category, event_type, data, script_id, line_number FROM events ORDER BY timestamp ASC");
+			const PAIRED_BEGIN = new Set(["Debugger.paused"]);
+			const PAIRED_END = new Set(["Debugger.resumed"]);
+			const traceEvents = allEvents.rows.map((row) => {
+				const ts = row[0] * 1e3;
+				const cat = row[1];
+				const name = row[2];
+				const dataStr = row[3];
+				let ph = "i";
+				if (PAIRED_BEGIN.has(name)) ph = "B";
+				else if (PAIRED_END.has(name)) ph = "E";
+				return {
+					name,
+					cat,
+					ph,
+					ts,
+					pid: 1,
+					tid: 1,
+					args: this.safeParseJSON(dataStr),
+					...ph === "i" ? { s: "g" } : {}
+				};
+			});
+			let finalOutputPath;
+			if (outputPath) finalOutputPath = outputPath;
+			else {
+				const { absolutePath } = await resolveArtifactPath({
+					category: "traces",
+					toolName: "trace_export",
+					ext: "json"
+				});
+				finalOutputPath = absolutePath;
+			}
+			const output = JSON.stringify(traceEvents, null, 2);
+			await writeFile(finalOutputPath, output, "utf-8");
+			return {
+				exportedPath: finalOutputPath,
+				eventCount: traceEvents.length,
+				format: "Chrome Trace Event JSON",
+				message: `Exported ${traceEvents.length} events to ${finalOutputPath}. Open in chrome://tracing or ui.perfetto.dev`
+			};
+		} finally {
+			if (tempDb) tempDb.close();
+		}
+	}
+	/**
+	* Get a TraceDB instance for reading — either from an explicit path
+	* or from the active recorder.
+	*/
+	getDbForReading(dbPath) {
+		if (dbPath) return new TraceDB({ dbPath });
+		const activeDb = this.recorder.getDB();
+		if (!activeDb) throw new Error("GRACEFUL: No active recording and no dbPath specified. Start a recording or provide a dbPath.");
+		activeDb.flush();
+		return activeDb;
+	}
+	/**
+	* Convert a row array + column names to an object.
+	*/
+	rowToObject(columns, row) {
+		const obj = {};
+		for (let i = 0; i < columns.length; i++) obj[columns[i]] = row[i];
+		return obj;
+	}
+	/**
+	* Safely parse JSON, returning the raw string on parse failure.
+	*/
+	safeParseJSON(str) {
+		try {
+			return JSON.parse(str);
+		} catch {
+			return str;
+		}
+	}
+	async handleSummarizeTrace(args) {
+		const detail = args["detail"] ?? "balanced";
+		const dbPath = args["dbPath"];
+		let db;
+		let shouldClose = false;
+		if (dbPath) {
+			db = new TraceDB({ dbPath });
+			shouldClose = true;
+		} else if (this.recorder.getState() === "recording") {
+			const activeDb = this.recorder.getDB();
+			if (!activeDb) throw new Error("Active recording has no database");
+			db = activeDb;
+		} else throw new Error("GRACEFUL: No trace database specified and no active recording");
+		try {
+			const events = db.query("SELECT timestamp, category, event_type, data, script_id, line_number FROM events ORDER BY timestamp").rows.map((row) => ({
+				timestamp: row[0],
+				category: row[1],
+				eventType: row[2],
+				data: typeof row[3] === "string" ? this.safeParseJSON(row[3]) : row[3],
+				scriptId: row[4],
+				lineNumber: row[5]
+			}));
+			const deltas = db.query("SELECT timestamp, address, old_value, new_value, size, value_type FROM memory_deltas ORDER BY timestamp").rows.map((row) => ({
+				timestamp: row[0],
+				address: row[1],
+				oldValue: row[2],
+				newValue: row[3],
+				size: row[4],
+				valueType: row[5]
+			}));
+			return {
+				events: summarizeEvents(events, detail),
+				memory: summarizeMemoryDeltas(deltas),
+				metadata: {
+					dbPath: dbPath ?? "active recording",
+					generatedAt: (/* @__PURE__ */ new Date()).toISOString()
+				}
+			};
+		} finally {
+			if (shouldClose) db.close();
+		}
+	}
+};
+//#endregion
+export { TraceToolHandlers };