@warlock.js/devtools 5.25.0

package/esm/collector.mjs

@@ -0,0 +1,185 @@
+import { detectNPlusOne } from "./n-plus-one.mjs";
+import { queryShape } from "./query-shape.mjs";
+
+//#region ../devtools/src/collector.ts
+const mailLimit = 100;
+const logLimit = 1e3;
+const backgroundLimit = 500;
+/**
+* Creates the in-memory devtools store.
+*
+* Read methods return shallow structural copies, including copied arrays, so consumers
+* cannot mutate collector-owned arrays. The individual nested entries are retained.
+*/
+function createCollector(options) {
+	const requests = /* @__PURE__ */ new Map();
+	const mails = /* @__PURE__ */ new Map();
+	const logs = [];
+	const background = {
+		queries: [],
+		cache: [],
+		logs: []
+	};
+	const listeners = /* @__PURE__ */ new Set();
+	let querySequence = 0;
+	const emit = (event) => {
+		for (const listener of listeners) try {
+			listener(event);
+		} catch {}
+	};
+	const addBackground = (list, value) => {
+		list.push(value);
+		if (list.length > backgroundLimit) list.shift();
+	};
+	return {
+		startRequest(request) {
+			requests.delete(request.id);
+			requests.set(request.id, {
+				...request,
+				phases: [],
+				queries: [],
+				cache: [],
+				logs: [],
+				mails: [],
+				warnings: []
+			});
+			while (requests.size > options.maxRequests) requests.delete(requests.keys().next().value);
+		},
+		endRequest(id, result) {
+			const request = requests.get(id);
+			if (!request) return;
+			request.status = result.status;
+			request.durationMs = result.durationMs;
+			request.error = result.error;
+			if (result.route !== void 0) request.route = result.route;
+			request.warnings = detectNPlusOne(request.queries, options.nPlusOneThreshold);
+			emit({
+				type: "request",
+				data: summary(request)
+			});
+		},
+		addPhase(requestId, phase) {
+			requests.get(requestId)?.phases.push(phase);
+		},
+		addQuery(requestId, query) {
+			const stored = {
+				...query,
+				id: `q${++querySequence}`,
+				shape: queryShape(query)
+			};
+			const request = requestId ? requests.get(requestId) : void 0;
+			if (request) request.queries.push(stored);
+			else addBackground(background.queries, stored);
+			return stored;
+		},
+		addCacheOperation(requestId, operation) {
+			const request = requestId ? requests.get(requestId) : void 0;
+			if (request) request.cache.push(operation);
+			else addBackground(background.cache, operation);
+		},
+		addLog(requestId, entry) {
+			const request = requestId ? requests.get(requestId) : void 0;
+			if (request) request.logs.push(entry);
+			else addBackground(background.logs, entry);
+			logs.unshift(entry);
+			if (logs.length > logLimit) logs.pop();
+			emit({
+				type: "log",
+				data: entry
+			});
+		},
+		addMail(mail) {
+			mails.delete(mail.id);
+			mails.set(mail.id, mail);
+			while (mails.size > mailLimit) mails.delete(mails.keys().next().value);
+			if (mail.requestId) requests.get(mail.requestId)?.mails.push(mail.id);
+			emit({
+				type: "mail",
+				data: mailSummary(mail)
+			});
+		},
+		listRequests() {
+			return [...requests.values()].reverse().map(summary);
+		},
+		getRequest(id) {
+			const request = requests.get(id);
+			return request && copyRequest(request);
+		},
+		listMails() {
+			return [...mails.values()].reverse().map(mailSummary);
+		},
+		getMail(id) {
+			const mail = mails.get(id);
+			return mail && {
+				...mail,
+				to: [...mail.to],
+				cc: [...mail.cc],
+				bcc: [...mail.bcc],
+				headers: { ...mail.headers },
+				attachments: [...mail.attachments]
+			};
+		},
+		listLogs(filter = {}) {
+			const module = filter.module?.toLowerCase();
+			return logs.filter((entry) => (!filter.level || entry.level === filter.level) && (!module || entry.module.toLowerCase().includes(module))).map((entry) => ({ ...entry }));
+		},
+		getBackground() {
+			return {
+				queries: [...background.queries],
+				cache: [...background.cache],
+				logs: [...background.logs]
+			};
+		},
+		subscribe(listener) {
+			listeners.add(listener);
+			return () => listeners.delete(listener);
+		},
+		clear() {
+			requests.clear();
+			mails.clear();
+			logs.length = 0;
+			background.queries.length = 0;
+			background.cache.length = 0;
+			background.logs.length = 0;
+		}
+	};
+}
+function summary(request) {
+	const { id, method, path, route, status, startedAt, durationMs } = request;
+	return {
+		id,
+		method,
+		path,
+		route,
+		status,
+		startedAt,
+		durationMs,
+		queryCount: request.queries.length,
+		warningCount: request.warnings.length
+	};
+}
+function mailSummary(mail) {
+	const { id, requestId, capturedAt, to, subject } = mail;
+	return {
+		id,
+		requestId,
+		capturedAt,
+		to: [...to],
+		subject
+	};
+}
+function copyRequest(request) {
+	return {
+		...request,
+		phases: [...request.phases],
+		queries: [...request.queries],
+		cache: [...request.cache],
+		logs: [...request.logs],
+		mails: [...request.mails],
+		warnings: [...request.warnings]
+	};
+}
+
+//#endregion
+export { createCollector };
+//# sourceMappingURL=collector.mjs.map

package/esm/collector.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"collector.mjs","names":[],"sources":["../../../../../../devtools/src/collector.ts"],"sourcesContent":["import type {\n  DevtoolsBackground,\n  DevtoolsCacheOperation,\n  DevtoolsCollector,\n  DevtoolsDisposer,\n  DevtoolsLogEntry,\n  DevtoolsMail,\n  DevtoolsMailSummary,\n  DevtoolsPhase,\n  DevtoolsQuery,\n  DevtoolsRequest,\n  DevtoolsRequestSummary,\n  DevtoolsStreamEvent,\n  ResolvedDevtoolsOptions,\n} from \"./types\";\nimport { detectNPlusOne } from \"./n-plus-one\";\nimport { queryShape } from \"./query-shape\";\n\nconst mailLimit = 100;\nconst logLimit = 1000;\nconst backgroundLimit = 500;\n\n/**\n * Creates the in-memory devtools store.\n *\n * Read methods return shallow structural copies, including copied arrays, so consumers\n * cannot mutate collector-owned arrays. The individual nested entries are retained.\n */\nexport function createCollector(options: ResolvedDevtoolsOptions): DevtoolsCollector {\n  const requests = new Map<string, DevtoolsRequest>();\n  const mails = new Map<string, DevtoolsMail>();\n  const logs: DevtoolsLogEntry[] = [];\n  const background: DevtoolsBackground = { queries: [], cache: [], logs: [] };\n  const listeners = new Set<(event: DevtoolsStreamEvent) => void>();\n  let querySequence = 0;\n\n  const emit = (event: DevtoolsStreamEvent) => {\n    for (const listener of listeners) {\n      try {\n        listener(event);\n      } catch {\n        /* Subscribers must not affect collection. */\n      }\n    }\n  };\n\n  const addBackground = <T>(list: T[], value: T) => {\n    list.push(value);\n    if (list.length > backgroundLimit) list.shift();\n  };\n\n  return {\n    startRequest(request) {\n      requests.delete(request.id);\n      requests.set(request.id, {\n        ...request,\n        phases: [],\n        queries: [],\n        cache: [],\n        logs: [],\n        mails: [],\n        warnings: [],\n      });\n      while (requests.size > options.maxRequests)\n        requests.delete(requests.keys().next().value as string);\n    },\n    endRequest(id, result) {\n      const request = requests.get(id);\n      if (!request) return;\n      request.status = result.status;\n      request.durationMs = result.durationMs;\n      request.error = result.error;\n      if (result.route !== undefined) request.route = result.route;\n      request.warnings = detectNPlusOne(request.queries, options.nPlusOneThreshold);\n      emit({ type: \"request\", data: summary(request) });\n    },\n    addPhase(requestId, phase) {\n      requests.get(requestId)?.phases.push(phase);\n    },\n    addQuery(requestId, query) {\n      const stored: DevtoolsQuery = {\n        ...query,\n        id: `q${++querySequence}`,\n        shape: queryShape(query),\n      };\n      const request = requestId ? requests.get(requestId) : undefined;\n      if (request) request.queries.push(stored);\n      else addBackground(background.queries, stored);\n      return stored;\n    },\n    addCacheOperation(requestId, operation) {\n      const request = requestId ? requests.get(requestId) : undefined;\n      if (request) request.cache.push(operation);\n      else addBackground(background.cache, operation);\n    },\n    addLog(requestId, entry) {\n      const request = requestId ? requests.get(requestId) : undefined;\n      if (request) request.logs.push(entry);\n      else addBackground(background.logs, entry);\n      logs.unshift(entry);\n      if (logs.length > logLimit) logs.pop();\n      emit({ type: \"log\", data: entry });\n    },\n    addMail(mail) {\n      mails.delete(mail.id);\n      mails.set(mail.id, mail);\n      while (mails.size > mailLimit) mails.delete(mails.keys().next().value as string);\n      if (mail.requestId) requests.get(mail.requestId)?.mails.push(mail.id);\n      emit({ type: \"mail\", data: mailSummary(mail) });\n    },\n    listRequests() {\n      return [...requests.values()].reverse().map(summary);\n    },\n    getRequest(id) {\n      const request = requests.get(id);\n      return request && copyRequest(request);\n    },\n    listMails() {\n      return [...mails.values()].reverse().map(mailSummary);\n    },\n    getMail(id) {\n      const mail = mails.get(id);\n      return (\n        mail && {\n          ...mail,\n          to: [...mail.to],\n          cc: [...mail.cc],\n          bcc: [...mail.bcc],\n          headers: { ...mail.headers },\n          attachments: [...mail.attachments],\n        }\n      );\n    },\n    listLogs(filter = {}) {\n      const module = filter.module?.toLowerCase();\n      return logs\n        .filter(\n          (entry) =>\n            (!filter.level || entry.level === filter.level) &&\n            (!module || entry.module.toLowerCase().includes(module)),\n        )\n        .map((entry) => ({ ...entry }));\n    },\n    getBackground() {\n      return {\n        queries: [...background.queries],\n        cache: [...background.cache],\n        logs: [...background.logs],\n      };\n    },\n    subscribe(listener): DevtoolsDisposer {\n      listeners.add(listener);\n      return () => listeners.delete(listener);\n    },\n    clear() {\n      requests.clear();\n      mails.clear();\n      logs.length = 0;\n      background.queries.length = 0;\n      background.cache.length = 0;\n      background.logs.length = 0;\n    },\n  };\n}\n\nfunction summary(request: DevtoolsRequest): DevtoolsRequestSummary {\n  const { id, method, path, route, status, startedAt, durationMs } = request;\n  return {\n    id,\n    method,\n    path,\n    route,\n    status,\n    startedAt,\n    durationMs,\n    queryCount: request.queries.length,\n    warningCount: request.warnings.length,\n  };\n}\n\nfunction mailSummary(mail: DevtoolsMail): DevtoolsMailSummary {\n  const { id, requestId, capturedAt, to, subject } = mail;\n  return { id, requestId, capturedAt, to: [...to], subject };\n}\n\nfunction copyRequest(request: DevtoolsRequest): DevtoolsRequest {\n  return {\n    ...request,\n    phases: [...request.phases],\n    queries: [...request.queries],\n    cache: [...request.cache],\n    logs: [...request.logs],\n    mails: [...request.mails],\n    warnings: [...request.warnings],\n  };\n}\n"],"mappings":"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"}

package/esm/current-request-id.mjs

@@ -0,0 +1,24 @@
+import { requestContext } from "@warlock.js/core";
+
+//#region ../devtools/src/current-request-id.ts
+/**
+* The current request's id (core's `request.id`, threaded through
+* `AsyncLocalStorage`), or `undefined` outside a request — sources feed
+* devtools' background bucket in that case.
+*
+* Only ever reached through `./sources/*`, which the connector imports
+* dynamically inside `boot()` — by then core is already running, so this
+* static import never drags core's runtime graph into config-load time (see
+* `devtools-connector.ts`).
+*/
+function currentRequestId() {
+	try {
+		return requestContext.getRequest()?.id;
+	} catch {
+		return;
+	}
+}
+
+//#endregion
+export { currentRequestId };
+//# sourceMappingURL=current-request-id.mjs.map

package/esm/current-request-id.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"current-request-id.mjs","names":[],"sources":["../../../../../../devtools/src/current-request-id.ts"],"sourcesContent":["import { requestContext } from \"@warlock.js/core\";\n\n/**\n * The current request's id (core's `request.id`, threaded through\n * `AsyncLocalStorage`), or `undefined` outside a request — sources feed\n * devtools' background bucket in that case.\n *\n * Only ever reached through `./sources/*`, which the connector imports\n * dynamically inside `boot()` — by then core is already running, so this\n * static import never drags core's runtime graph into config-load time (see\n * `devtools-connector.ts`).\n */\nexport function currentRequestId(): string | undefined {\n  try {\n    return requestContext.getRequest()?.id;\n  } catch {\n    return undefined;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;AAYA,SAAgB,mBAAuC;CACrD,IAAI;EACF,OAAO,eAAe,WAAW,CAAC,EAAE;CACtC,QAAQ;EACN;CACF;AACF"}

package/esm/devtools-connector.d.mts

@@ -0,0 +1,26 @@
+import { DevtoolsOptions } from "./types.mjs";
+import { Connector } from "@warlock.js/core";
+
+//#region ../devtools/src/devtools-connector.d.ts
+/** Options accepted by `devtoolsConnector()`. */
+type DevtoolsConnectorOptions = DevtoolsOptions;
+/**
+ * Construct the devtools connector.
+ *
+ * Refuses to run outside development: `boot()` checks
+ * `Application.runtimeStrategy` and, when it isn't `"development"`, logs one
+ * warning and returns without mounting a route or subscribing to anything.
+ * In development it attaches every source (tracing, queries, cache, mail,
+ * logs), then mounts the dashboard's routes on the HTTP server — before it
+ * starts listening, the only point in the boot sequence where mounting is
+ * possible (see `queue/src/dashboard-boot.ts` for the same constraint).
+ *
+ * Apps don't call this: `warlock dev` registers it automatically when the
+ * package is installed (`warlock add devtools`). Keep it OUT of
+ * `warlock.config.ts` — devtools is a dev dependency, so a production
+ * install doesn't have it and a config import of it would fail there.
+ */
+declare function devtoolsConnector(options?: DevtoolsConnectorOptions): Connector;
+//#endregion
+export { devtoolsConnector };
+//# sourceMappingURL=devtools-connector.d.mts.map

package/esm/devtools-connector.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"devtools-connector.d.mts","names":[],"sources":["../../../../../../devtools/src/devtools-connector.ts"],"mappings":";;;;AA8CoF;AAAA,KAlBxE,wBAAA,GAA2B,eAAe;;;;;;;;;;;;;;;;;iBAkBtC,iBAAA,CAAkB,OAAA,GAAS,wBAAA,GAAgC,SAAS"}

package/esm/devtools-connector.mjs

@@ -0,0 +1,112 @@
+import { createCollector } from "./collector.mjs";
+import { resolveDevtoolsOptions } from "./options.mjs";
+import { attachCacheSource } from "./sources/cache-source.mjs";
+import { attachLogSource } from "./sources/log-source.mjs";
+import { attachMailSource } from "./sources/mail-source.mjs";
+import { attachQuerySource } from "./sources/query-source.mjs";
+import { attachTracingSource } from "./sources/tracing-source.mjs";
+
+//#region ../devtools/src/devtools-connector.ts
+/**
+* Boots after the queue connector (priority 11), which is the last
+* built-in/framework connector to claim a priority; devtools has nothing
+* that depends on it, so it simply goes last.
+*/
+const DEVTOOLS_CONNECTOR_PRIORITY = 12;
+/**
+* Construct the devtools connector.
+*
+* Refuses to run outside development: `boot()` checks
+* `Application.runtimeStrategy` and, when it isn't `"development"`, logs one
+* warning and returns without mounting a route or subscribing to anything.
+* In development it attaches every source (tracing, queries, cache, mail,
+* logs), then mounts the dashboard's routes on the HTTP server — before it
+* starts listening, the only point in the boot sequence where mounting is
+* possible (see `queue/src/dashboard-boot.ts` for the same constraint).
+*
+* Apps don't call this: `warlock dev` registers it automatically when the
+* package is installed (`warlock add devtools`). Keep it OUT of
+* `warlock.config.ts` — devtools is a dev dependency, so a production
+* install doesn't have it and a config import of it would fail there.
+*/
+function devtoolsConnector(options = {}) {
+	let active = false;
+	const disposers = [];
+	const connector = {
+		name: "devtools",
+		priority: 12,
+		lifecyclePhase: "late",
+		isActive: () => active,
+		async boot() {
+			const { Application, getHttpServer } = await import("@warlock.js/core");
+			const { log } = await import("@warlock.js/logger");
+			if (Application.runtimeStrategy !== "development") {
+				log.warn("devtools", "disabled", "@warlock.js/devtools only runs in development; it is not mounted");
+				return;
+			}
+			const resolved = resolveDevtoolsOptions(options);
+			const collector = createCollector(resolved);
+			await attachSource(log, "tracing", () => attachTracingSource(collector, resolved));
+			await attachSource(log, "query", () => attachQuerySource(collector));
+			await attachSource(log, "cache", () => attachCacheSource(collector));
+			await attachSource(log, "mail", () => attachMailSource(collector));
+			await attachSource(log, "log", () => attachLogSource(collector));
+			const { mountDevtoolsRoutes } = await import("./server/index.mjs");
+			mountDevtoolsRoutes(getHttpServer(), {
+				collector,
+				options: resolved,
+				isDevelopment: () => Application.runtimeStrategy === "development",
+				explain: (query) => explainQuery(query),
+				listRoutes: () => listRoutes()
+			});
+			disposers.push(collector.subscribe((event) => {
+				if (event.type !== "request" || event.data.warningCount === 0) return;
+				for (const warning of collector.getRequest(event.data.id)?.warnings ?? []) {
+					const where = warning.caller ? ` — ${warning.caller.file}:${warning.caller.line}` : "";
+					log.warn("devtools", "n+1", `${warning.message}${where} (${event.data.method} ${event.data.path})`);
+				}
+			}));
+			active = true;
+			log.info("devtools", "ready", `devtools ready at ${resolved.path}`);
+		},
+		async start() {},
+		async restart() {
+			await connector.shutdown();
+			await connector.start();
+		},
+		async shutdown() {
+			for (const dispose of disposers.splice(0)) dispose();
+			active = false;
+		},
+		shouldRestart: () => false
+	};
+	/** Attaches one source, logging and continuing when it fails to attach. */
+	async function attachSource(logger, name, attach) {
+		try {
+			disposers.push(await attach());
+		} catch (error) {
+			logger.warn("devtools", "source-failed", `devtools' ${name} source failed to attach: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+	return connector;
+}
+/** Runs `EXPLAIN (FORMAT JSON)` for a stored Postgres query on its own connection. */
+async function explainQuery(query) {
+	const { dataSourceRegistry } = await import("@warlock.js/cascade");
+	const { rows } = await dataSourceRegistry.get(query.connection).raw(`EXPLAIN (FORMAT JSON) ${query.sql}`, query.bindings);
+	return rows;
+}
+/** Lists every registered HTTP route — the same source `warlock routes --json` reads. */
+async function listRoutes() {
+	const { router } = await import("@warlock.js/core");
+	return router.list().map((route) => ({
+		method: route.method.toUpperCase(),
+		path: route.path,
+		name: route.name,
+		middleware: route.middleware?.map((middleware) => middleware.name || "anonymous")
+	}));
+}
+
+//#endregion
+export { devtoolsConnector };
+//# sourceMappingURL=devtools-connector.mjs.map

package/esm/devtools-connector.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"devtools-connector.mjs","names":[],"sources":["../../../../../../devtools/src/devtools-connector.ts"],"sourcesContent":["/**\n * The devtools connector for `warlock.config.ts > connectors`.\n *\n * Deliberately a plain object with TYPE-ONLY imports from core: the config\n * file that constructs it must not drag core's runtime graph in at\n * config-load time. Core is imported lazily inside `boot()`, where the app\n * has already loaded it — see `queue/src/queue-connector.ts`, the pattern\n * this mirrors.\n */\nimport type { Connector, ConnectorLifecyclePhase } from \"@warlock.js/core\";\nimport { createCollector } from \"./collector\";\nimport { resolveDevtoolsOptions } from \"./options\";\nimport type { DevtoolsRouteRow } from \"./server\";\nimport { attachCacheSource } from \"./sources/cache-source\";\nimport { attachLogSource } from \"./sources/log-source\";\nimport { attachMailSource } from \"./sources/mail-source\";\nimport { attachQuerySource } from \"./sources/query-source\";\nimport { attachTracingSource } from \"./sources/tracing-source\";\nimport type { DevtoolsDisposer, DevtoolsOptions, DevtoolsQuery } from \"./types\";\n\n/**\n * Boots after the queue connector (priority 11), which is the last\n * built-in/framework connector to claim a priority; devtools has nothing\n * that depends on it, so it simply goes last.\n */\nexport const DEVTOOLS_CONNECTOR_PRIORITY = 12;\n\n/** Options accepted by `devtoolsConnector()`. */\nexport type DevtoolsConnectorOptions = DevtoolsOptions;\n\n/**\n * Construct the devtools connector.\n *\n * Refuses to run outside development: `boot()` checks\n * `Application.runtimeStrategy` and, when it isn't `\"development\"`, logs one\n * warning and returns without mounting a route or subscribing to anything.\n * In development it attaches every source (tracing, queries, cache, mail,\n * logs), then mounts the dashboard's routes on the HTTP server — before it\n * starts listening, the only point in the boot sequence where mounting is\n * possible (see `queue/src/dashboard-boot.ts` for the same constraint).\n *\n * Apps don't call this: `warlock dev` registers it automatically when the\n * package is installed (`warlock add devtools`). Keep it OUT of\n * `warlock.config.ts` — devtools is a dev dependency, so a production\n * install doesn't have it and a config import of it would fail there.\n */\nexport function devtoolsConnector(options: DevtoolsConnectorOptions = {}): Connector {\n  let active = false;\n  const disposers: DevtoolsDisposer[] = [];\n\n  const connector: Connector = {\n    name: \"devtools\",\n    priority: DEVTOOLS_CONNECTOR_PRIORITY,\n    // Core's `ConnectorLifecyclePhase.Late`; spelled out so this module stays\n    // free of a runtime import of core.\n    lifecyclePhase: \"late\" as ConnectorLifecyclePhase,\n    isActive: () => active,\n    async boot() {\n      const { Application, getHttpServer } = await import(\"@warlock.js/core\");\n      const { log } = await import(\"@warlock.js/logger\");\n\n      if (Application.runtimeStrategy !== \"development\") {\n        log.warn(\n          \"devtools\",\n          \"disabled\",\n          \"@warlock.js/devtools only runs in development; it is not mounted\",\n        );\n        return;\n      }\n\n      const resolved = resolveDevtoolsOptions(options);\n      const collector = createCollector(resolved);\n\n      await attachSource(log, \"tracing\", () => attachTracingSource(collector, resolved));\n      await attachSource(log, \"query\", () => attachQuerySource(collector));\n      await attachSource(log, \"cache\", () => attachCacheSource(collector));\n      await attachSource(log, \"mail\", () => attachMailSource(collector));\n      await attachSource(log, \"log\", () => attachLogSource(collector));\n\n      const { mountDevtoolsRoutes } = await import(\"./server\");\n\n      mountDevtoolsRoutes(getHttpServer(), {\n        collector,\n        options: resolved,\n        isDevelopment: () => Application.runtimeStrategy === \"development\",\n        explain: (query) => explainQuery(query),\n        listRoutes: () => listRoutes(),\n      });\n\n      // An N+1 is worth a terminal line, not just a badge the developer has\n      // to go looking for: one warning per offending query shape, with the\n      // line that issued it.\n      disposers.push(\n        collector.subscribe((event) => {\n          if (event.type !== \"request\" || event.data.warningCount === 0) return;\n\n          for (const warning of collector.getRequest(event.data.id)?.warnings ?? []) {\n            const where = warning.caller ? ` — ${warning.caller.file}:${warning.caller.line}` : \"\";\n\n            log.warn(\n              \"devtools\",\n              \"n+1\",\n              `${warning.message}${where} (${event.data.method} ${event.data.path})`,\n            );\n          }\n        }),\n      );\n\n      active = true;\n\n      log.info(\"devtools\", \"ready\", `devtools ready at ${resolved.path}`);\n    },\n    async start() {},\n    async restart() {\n      await connector.shutdown();\n      await connector.start();\n    },\n    async shutdown() {\n      for (const dispose of disposers.splice(0)) dispose();\n      active = false;\n    },\n    shouldRestart: () => false,\n  };\n\n  /** Attaches one source, logging and continuing when it fails to attach. */\n  async function attachSource(\n    logger: { warn: (module: string, action: string, message: string) => unknown },\n    name: string,\n    attach: () => Promise<DevtoolsDisposer>,\n  ): Promise<void> {\n    try {\n      disposers.push(await attach());\n    } catch (error) {\n      logger.warn(\n        \"devtools\",\n        \"source-failed\",\n        `devtools' ${name} source failed to attach: ${error instanceof Error ? error.message : String(error)}`,\n      );\n    }\n  }\n\n  return connector;\n}\n\n/** Runs `EXPLAIN (FORMAT JSON)` for a stored Postgres query on its own connection. */\nasync function explainQuery(query: DevtoolsQuery): Promise<unknown> {\n  const { dataSourceRegistry } = await import(\"@warlock.js/cascade\");\n  const dataSource = dataSourceRegistry.get(query.connection);\n  const { rows } = await dataSource.raw(`EXPLAIN (FORMAT JSON) ${query.sql}`, query.bindings);\n\n  return rows;\n}\n\n/** Lists every registered HTTP route — the same source `warlock routes --json` reads. */\nasync function listRoutes(): Promise<DevtoolsRouteRow[]> {\n  const { router } = await import(\"@warlock.js/core\");\n\n  return router.list().map((route) => ({\n    method: route.method.toUpperCase(),\n    path: route.path,\n    name: route.name,\n    middleware: route.middleware?.map((middleware) => middleware.name || \"anonymous\"),\n  }));\n}\n"],"mappings":";;;;;;;;;;;;;;AAyBA,MAAa,8BAA8B;;;;;;;;;;;;;;;;;AAqB3C,SAAgB,kBAAkB,UAAoC,CAAC,GAAc;CACnF,IAAI,SAAS;CACb,MAAM,YAAgC,CAAC;CAEvC,MAAM,YAAuB;EAC3B,MAAM;EACN;EAGA,gBAAgB;EAChB,gBAAgB;EAChB,MAAM,OAAO;GACX,MAAM,EAAE,aAAa,kBAAkB,MAAM,OAAO;GACpD,MAAM,EAAE,QAAQ,MAAM,OAAO;GAE7B,IAAI,YAAY,oBAAoB,eAAe;IACjD,IAAI,KACF,YACA,YACA,kEACF;IACA;GACF;GAEA,MAAM,WAAW,uBAAuB,OAAO;GAC/C,MAAM,YAAY,gBAAgB,QAAQ;GAE1C,MAAM,aAAa,KAAK,iBAAiB,oBAAoB,WAAW,QAAQ,CAAC;GACjF,MAAM,aAAa,KAAK,eAAe,kBAAkB,SAAS,CAAC;GACnE,MAAM,aAAa,KAAK,eAAe,kBAAkB,SAAS,CAAC;GACnE,MAAM,aAAa,KAAK,cAAc,iBAAiB,SAAS,CAAC;GACjE,MAAM,aAAa,KAAK,aAAa,gBAAgB,SAAS,CAAC;GAE/D,MAAM,EAAE,wBAAwB,MAAM,OAAO;GAE7C,oBAAoB,cAAc,GAAG;IACnC;IACA,SAAS;IACT,qBAAqB,YAAY,oBAAoB;IACrD,UAAU,UAAU,aAAa,KAAK;IACtC,kBAAkB,WAAW;GAC/B,CAAC;GAKD,UAAU,KACR,UAAU,WAAW,UAAU;IAC7B,IAAI,MAAM,SAAS,aAAa,MAAM,KAAK,iBAAiB,GAAG;IAE/D,KAAK,MAAM,WAAW,UAAU,WAAW,MAAM,KAAK,EAAE,CAAC,EAAE,YAAY,CAAC,GAAG;KACzE,MAAM,QAAQ,QAAQ,SAAS,MAAM,QAAQ,OAAO,KAAK,GAAG,QAAQ,OAAO,SAAS;KAEpF,IAAI,KACF,YACA,OACA,GAAG,QAAQ,UAAU,MAAM,IAAI,MAAM,KAAK,OAAO,GAAG,MAAM,KAAK,KAAK,EACtE;IACF;GACF,CAAC,CACH;GAEA,SAAS;GAET,IAAI,KAAK,YAAY,SAAS,qBAAqB,SAAS,MAAM;EACpE;EACA,MAAM,QAAQ,CAAC;EACf,MAAM,UAAU;GACd,MAAM,UAAU,SAAS;GACzB,MAAM,UAAU,MAAM;EACxB;EACA,MAAM,WAAW;GACf,KAAK,MAAM,WAAW,UAAU,OAAO,CAAC,GAAG,QAAQ;GACnD,SAAS;EACX;EACA,qBAAqB;CACvB;;CAGA,eAAe,aACb,QACA,MACA,QACe;EACf,IAAI;GACF,UAAU,KAAK,MAAM,OAAO,CAAC;EAC/B,SAAS,OAAO;GACd,OAAO,KACL,YACA,iBACA,aAAa,KAAK,4BAA4B,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,GACrG;EACF;CACF;CAEA,OAAO;AACT;;AAGA,eAAe,aAAa,OAAwC;CAClE,MAAM,EAAE,uBAAuB,MAAM,OAAO;CAE5C,MAAM,EAAE,SAAS,MADE,mBAAmB,IAAI,MAAM,UAChB,CAAC,CAAC,IAAI,yBAAyB,MAAM,OAAO,MAAM,QAAQ;CAE1F,OAAO;AACT;;AAGA,eAAe,aAA0C;CACvD,MAAM,EAAE,WAAW,MAAM,OAAO;CAEhC,OAAO,OAAO,KAAK,CAAC,CAAC,KAAK,WAAW;EACnC,QAAQ,MAAM,OAAO,YAAY;EACjC,MAAM,MAAM;EACZ,MAAM,MAAM;EACZ,YAAY,MAAM,YAAY,KAAK,eAAe,WAAW,QAAQ,WAAW;CAClF,EAAE;AACJ"}

package/esm/index.d.mts

@@ -0,0 +1,3 @@
+import { DevtoolsBackground, DevtoolsCacheOperation, DevtoolsCallerLocation, DevtoolsCollector, DevtoolsDisposer, DevtoolsLogEntry, DevtoolsMail, DevtoolsMailAttachment, DevtoolsMailSummary, DevtoolsOptions, DevtoolsPhase, DevtoolsQuery, DevtoolsRequest, DevtoolsRequestSummary, DevtoolsStreamEvent, DevtoolsWarning, ResolvedDevtoolsOptions } from "./types.mjs";
+import { devtoolsConnector } from "./devtools-connector.mjs";
+export { type DevtoolsBackground, type DevtoolsCacheOperation, type DevtoolsCallerLocation, type DevtoolsCollector, type DevtoolsDisposer, type DevtoolsLogEntry, type DevtoolsMail, type DevtoolsMailAttachment, type DevtoolsMailSummary, type DevtoolsOptions, type DevtoolsPhase, type DevtoolsQuery, type DevtoolsRequest, type DevtoolsRequestSummary, type DevtoolsStreamEvent, type DevtoolsWarning, type ResolvedDevtoolsOptions, devtoolsConnector };

package/esm/index.mjs

@@ -0,0 +1,3 @@
+import { devtoolsConnector } from "./devtools-connector.mjs";
+
+export { devtoolsConnector };

package/esm/n-plus-one.mjs

@@ -0,0 +1,36 @@
+//#region ../devtools/src/n-plus-one.ts
+/** Finds repeated query shapes whose occurrence count reaches the supplied threshold. */
+function detectNPlusOne(queries, threshold) {
+	const groups = /* @__PURE__ */ new Map();
+	for (const query of queries) groups.set(query.shape, [...groups.get(query.shape) ?? [], query]);
+	return [...groups.entries()].filter(([, grouped]) => grouped.length >= threshold).sort(([, left], [, right]) => right.length - left.length).map(([shape, grouped]) => ({
+		type: "n+1",
+		shape,
+		count: grouped.length,
+		message: `N+1: ${grouped.length}× "${truncate(shape, 120)}"`,
+		...mostFrequentCaller(grouped) ? { caller: mostFrequentCaller(grouped) } : {}
+	}));
+}
+function truncate(value, maximum) {
+	return value.length > maximum ? `${value.slice(0, maximum - 1)}…` : value;
+}
+function mostFrequentCaller(queries) {
+	const callers = /* @__PURE__ */ new Map();
+	for (const query of queries) {
+		if (!query.caller) continue;
+		const key = `${query.caller.file}:${query.caller.line}`;
+		const found = callers.get(key);
+		callers.set(key, found ? {
+			...found,
+			count: found.count + 1
+		} : {
+			caller: query.caller,
+			count: 1
+		});
+	}
+	return [...callers.values()].sort((left, right) => right.count - left.count)[0]?.caller;
+}
+
+//#endregion
+export { detectNPlusOne };
+//# sourceMappingURL=n-plus-one.mjs.map

package/esm/n-plus-one.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"n-plus-one.mjs","names":[],"sources":["../../../../../../devtools/src/n-plus-one.ts"],"sourcesContent":["import type { DevtoolsCallerLocation, DevtoolsQuery, DevtoolsWarning } from \"./types\";\n\n/** Finds repeated query shapes whose occurrence count reaches the supplied threshold. */\nexport function detectNPlusOne(queries: DevtoolsQuery[], threshold: number): DevtoolsWarning[] {\n  const groups = new Map<string, DevtoolsQuery[]>();\n  for (const query of queries) groups.set(query.shape, [...(groups.get(query.shape) ?? []), query]);\n\n  return [...groups.entries()]\n    .filter(([, grouped]) => grouped.length >= threshold)\n    .sort(([, left], [, right]) => right.length - left.length)\n    .map(([shape, grouped]) => ({\n      type: \"n+1\" as const,\n      shape,\n      count: grouped.length,\n      message: `N+1: ${grouped.length}× \"${truncate(shape, 120)}\"`,\n      ...(mostFrequentCaller(grouped) ? { caller: mostFrequentCaller(grouped) } : {}),\n    }));\n}\n\nfunction truncate(value: string, maximum: number): string {\n  return value.length > maximum ? `${value.slice(0, maximum - 1)}…` : value;\n}\n\nfunction mostFrequentCaller(queries: DevtoolsQuery[]): DevtoolsCallerLocation | undefined {\n  const callers = new Map<string, { caller: DevtoolsCallerLocation; count: number }>();\n  for (const query of queries) {\n    if (!query.caller) continue;\n    const key = `${query.caller.file}:${query.caller.line}`;\n    const found = callers.get(key);\n    callers.set(\n      key,\n      found ? { ...found, count: found.count + 1 } : { caller: query.caller, count: 1 },\n    );\n  }\n  return [...callers.values()].sort((left, right) => right.count - left.count)[0]?.caller;\n}\n"],"mappings":";;AAGA,SAAgB,eAAe,SAA0B,WAAsC;CAC7F,MAAM,yBAAS,IAAI,IAA6B;CAChD,KAAK,MAAM,SAAS,SAAS,OAAO,IAAI,MAAM,OAAO,CAAC,GAAI,OAAO,IAAI,MAAM,KAAK,KAAK,CAAC,GAAI,KAAK,CAAC;CAEhG,OAAO,CAAC,GAAG,OAAO,QAAQ,CAAC,CAAC,CACzB,QAAQ,GAAG,aAAa,QAAQ,UAAU,SAAS,CAAC,CACpD,MAAM,GAAG,OAAO,GAAG,WAAW,MAAM,SAAS,KAAK,MAAM,CAAC,CACzD,KAAK,CAAC,OAAO,cAAc;EAC1B,MAAM;EACN;EACA,OAAO,QAAQ;EACf,SAAS,QAAQ,QAAQ,OAAO,KAAK,SAAS,OAAO,GAAG,EAAE;EAC1D,GAAI,mBAAmB,OAAO,IAAI,EAAE,QAAQ,mBAAmB,OAAO,EAAE,IAAI,CAAC;CAC/E,EAAE;AACN;AAEA,SAAS,SAAS,OAAe,SAAyB;CACxD,OAAO,MAAM,SAAS,UAAU,GAAG,MAAM,MAAM,GAAG,UAAU,CAAC,EAAE,KAAK;AACtE;AAEA,SAAS,mBAAmB,SAA8D;CACxF,MAAM,0BAAU,IAAI,IAA+D;CACnF,KAAK,MAAM,SAAS,SAAS;EAC3B,IAAI,CAAC,MAAM,QAAQ;EACnB,MAAM,MAAM,GAAG,MAAM,OAAO,KAAK,GAAG,MAAM,OAAO;EACjD,MAAM,QAAQ,QAAQ,IAAI,GAAG;EAC7B,QAAQ,IACN,KACA,QAAQ;GAAE,GAAG;GAAO,OAAO,MAAM,QAAQ;EAAE,IAAI;GAAE,QAAQ,MAAM;GAAQ,OAAO;EAAE,CAClF;CACF;CACA,OAAO,CAAC,GAAG,QAAQ,OAAO,CAAC,CAAC,CAAC,MAAM,MAAM,UAAU,MAAM,QAAQ,KAAK,KAAK,CAAC,CAAC,EAAE,EAAE;AACnF"}

package/esm/options.mjs

@@ -0,0 +1,19 @@
+//#region ../devtools/src/options.ts
+/** Resolves dashboard options and rejects invalid capacity or URL-prefix values. */
+function resolveDevtoolsOptions(options = {}) {
+	const path = (options.path ?? "/__warlock").replace(/\/+$/, "");
+	const maxRequests = options.maxRequests ?? 200;
+	const nPlusOneThreshold = options.nPlusOneThreshold ?? 5;
+	if (!path || !path.startsWith("/")) throw new Error("Devtools option \"path\" must be a non-root path starting with \"/\".");
+	if (maxRequests < 1) throw new Error("Devtools option \"maxRequests\" must be at least 1.");
+	if (nPlusOneThreshold < 2) throw new Error("Devtools option \"nPlusOneThreshold\" must be at least 2.");
+	return {
+		path,
+		maxRequests,
+		nPlusOneThreshold
+	};
+}
+
+//#endregion
+export { resolveDevtoolsOptions };
+//# sourceMappingURL=options.mjs.map

package/esm/options.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.mjs","names":[],"sources":["../../../../../../devtools/src/options.ts"],"sourcesContent":["import type { DevtoolsOptions, ResolvedDevtoolsOptions } from \"./types\";\n\n/** Resolves dashboard options and rejects invalid capacity or URL-prefix values. */\nexport function resolveDevtoolsOptions(options: DevtoolsOptions = {}): ResolvedDevtoolsOptions {\n  const path = (options.path ?? \"/__warlock\").replace(/\\/+$/, \"\");\n  const maxRequests = options.maxRequests ?? 200;\n  const nPlusOneThreshold = options.nPlusOneThreshold ?? 5;\n\n  if (!path || !path.startsWith(\"/\")) {\n    throw new Error('Devtools option \"path\" must be a non-root path starting with \"/\".');\n  }\n\n  if (maxRequests < 1) {\n    throw new Error('Devtools option \"maxRequests\" must be at least 1.');\n  }\n\n  if (nPlusOneThreshold < 2) {\n    throw new Error('Devtools option \"nPlusOneThreshold\" must be at least 2.');\n  }\n\n  return { path, maxRequests, nPlusOneThreshold };\n}\n"],"mappings":";;AAGA,SAAgB,uBAAuB,UAA2B,CAAC,GAA4B;CAC7F,MAAM,QAAQ,QAAQ,QAAQ,aAAY,CAAE,QAAQ,QAAQ,EAAE;CAC9D,MAAM,cAAc,QAAQ,eAAe;CAC3C,MAAM,oBAAoB,QAAQ,qBAAqB;CAEvD,IAAI,CAAC,QAAQ,CAAC,KAAK,WAAW,GAAG,GAC/B,MAAM,IAAI,MAAM,uEAAmE;CAGrF,IAAI,cAAc,GAChB,MAAM,IAAI,MAAM,qDAAmD;CAGrE,IAAI,oBAAoB,GACtB,MAAM,IAAI,MAAM,2DAAyD;CAG3E,OAAO;EAAE;EAAM;EAAa;CAAkB;AAChD"}

package/esm/query-shape.mjs

@@ -0,0 +1,27 @@
+//#region ../devtools/src/query-shape.ts
+const numericLiteral = /(?<![\w$])[-+]?(?:\d+(?:\.\d+)?|\.\d+)(?![\w$])/g;
+const quotedLiteral = /'(?:''|[^'])*'/g;
+/** Returns a binding-independent shape for a database query. */
+function queryShape(query) {
+	if (query.driver === "postgres") return (query.sql ?? "").replace(quotedLiteral, "?").replace(numericLiteral, "?").replace(/\s+/g, " ").trim();
+	return `${query.collection ?? ""}.${query.command ?? ""} ${JSON.stringify(normalizeMongoValue(query.pipeline))}`;
+}
+function normalizeMongoValue(value) {
+	if (isMongoLeaf(value)) return "?";
+	if (Array.isArray(value)) {
+		if (value.every(isMongoLeaf)) return ["?"];
+		return value.map(normalizeMongoValue);
+	}
+	const record = value;
+	return Object.fromEntries(Object.keys(record).map((key) => [key, normalizeMongoValue(record[key])]));
+}
+function isMongoLeaf(value) {
+	if (value === null || typeof value !== "object") return true;
+	if (value instanceof Date) return true;
+	const record = value;
+	return typeof record.toHexString === "function" || typeof record.$oid === "string";
+}
+
+//#endregion
+export { queryShape };
+//# sourceMappingURL=query-shape.mjs.map

package/esm/query-shape.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-shape.mjs","names":[],"sources":["../../../../../../devtools/src/query-shape.ts"],"sourcesContent":["import type { DevtoolsQuery } from \"./types\";\n\ntype QueryShapeInput = Pick<\n  DevtoolsQuery,\n  \"driver\" | \"sql\" | \"collection\" | \"command\" | \"pipeline\"\n>;\n\nconst numericLiteral = /(?<![\\w$])[-+]?(?:\\d+(?:\\.\\d+)?|\\.\\d+)(?![\\w$])/g;\nconst quotedLiteral = /'(?:''|[^'])*'/g;\n\n/** Returns a binding-independent shape for a database query. */\nexport function queryShape(query: QueryShapeInput): string {\n  if (query.driver === \"postgres\") {\n    return (query.sql ?? \"\")\n      .replace(quotedLiteral, \"?\")\n      .replace(numericLiteral, \"?\")\n      .replace(/\\s+/g, \" \")\n      .trim();\n  }\n\n  return `${query.collection ?? \"\"}.${query.command ?? \"\"} ${JSON.stringify(normalizeMongoValue(query.pipeline))}`;\n}\n\nfunction normalizeMongoValue(value: unknown): unknown {\n  if (isMongoLeaf(value)) return \"?\";\n\n  if (Array.isArray(value)) {\n    if (value.every(isMongoLeaf)) return [\"?\"];\n    return value.map(normalizeMongoValue);\n  }\n\n  const record = value as Record<string, unknown>;\n  return Object.fromEntries(\n    Object.keys(record).map((key) => [key, normalizeMongoValue(record[key])]),\n  );\n}\n\nfunction isMongoLeaf(value: unknown): boolean {\n  if (value === null || typeof value !== \"object\") return true;\n  if (value instanceof Date) return true;\n  const record = value as Record<string, unknown>;\n  return typeof record.toHexString === \"function\" || typeof record.$oid === \"string\";\n}\n"],"mappings":";AAOA,MAAM,iBAAiB;AACvB,MAAM,gBAAgB;;AAGtB,SAAgB,WAAW,OAAgC;CACzD,IAAI,MAAM,WAAW,YACnB,QAAQ,MAAM,OAAO,GAAE,CACpB,QAAQ,eAAe,GAAG,CAAC,CAC3B,QAAQ,gBAAgB,GAAG,CAAC,CAC5B,QAAQ,QAAQ,GAAG,CAAC,CACpB,KAAK;CAGV,OAAO,GAAG,MAAM,cAAc,GAAG,GAAG,MAAM,WAAW,GAAG,GAAG,KAAK,UAAU,oBAAoB,MAAM,QAAQ,CAAC;AAC/G;AAEA,SAAS,oBAAoB,OAAyB;CACpD,IAAI,YAAY,KAAK,GAAG,OAAO;CAE/B,IAAI,MAAM,QAAQ,KAAK,GAAG;EACxB,IAAI,MAAM,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG;EACzC,OAAO,MAAM,IAAI,mBAAmB;CACtC;CAEA,MAAM,SAAS;CACf,OAAO,OAAO,YACZ,OAAO,KAAK,MAAM,CAAC,CAAC,KAAK,QAAQ,CAAC,KAAK,oBAAoB,OAAO,IAAI,CAAC,CAAC,CAC1E;AACF;AAEA,SAAS,YAAY,OAAyB;CAC5C,IAAI,UAAU,QAAQ,OAAO,UAAU,UAAU,OAAO;CACxD,IAAI,iBAAiB,MAAM,OAAO;CAClC,MAAM,SAAS;CACf,OAAO,OAAO,OAAO,gBAAgB,cAAc,OAAO,OAAO,SAAS;AAC5E"}

package/esm/safe-value.mjs

@@ -0,0 +1,63 @@
+//#region ../devtools/src/safe-value.ts
+const MAX_DEPTH = 6;
+/**
+* A JSON-safe snapshot of a value devtools keeps for later display.
+*
+* Log contexts and phase attributes are app data: they can hold live objects
+* (a request, its socket) whose graphs are circular and which must not be kept
+* alive by the collector anyway. Plain objects and arrays are copied; anything
+* with a `toJSON()` is serialized through it; other class instances collapse
+* to `[ClassName]`, cycles to `[Circular]`, and nesting past a fixed depth to
+* `[Object]` / `[Array]`.
+*/
+function toSafeValue(value) {
+	return snapshot(value, 0, /* @__PURE__ */ new WeakSet());
+}
+function snapshot(value, depth, seen) {
+	if (value === null || value === void 0) return value;
+	switch (typeof value) {
+		case "string":
+		case "number":
+		case "boolean": return value;
+		case "bigint": return value.toString();
+		case "symbol": return value.toString();
+		case "function": return;
+	}
+	const object = value;
+	if (seen.has(object)) return "[Circular]";
+	if (value instanceof Date) return Number.isNaN(value.getTime()) ? "Invalid Date" : value.toISOString();
+	if (value instanceof Error) return {
+		name: value.name,
+		message: value.message
+	};
+	if (depth >= MAX_DEPTH) return Array.isArray(value) ? "[Array]" : "[Object]";
+	seen.add(object);
+	try {
+		if (Array.isArray(value)) return value.map((item) => snapshot(item, depth + 1, seen));
+		const prototype = Object.getPrototypeOf(object);
+		if (prototype !== Object.prototype && prototype !== null) {
+			const toJSON = object.toJSON;
+			if (typeof toJSON === "function") try {
+				return snapshot(toJSON.call(object), depth + 1, seen);
+			} catch {
+				return `[${constructorName(object)}]`;
+			}
+			return `[${constructorName(object)}]`;
+		}
+		const copy = {};
+		for (const [key, entry] of Object.entries(object)) {
+			const safe = snapshot(entry, depth + 1, seen);
+			if (safe !== void 0) copy[key] = safe;
+		}
+		return copy;
+	} finally {
+		seen.delete(object);
+	}
+}
+function constructorName(object) {
+	return object.constructor?.name || "Object";
+}
+
+//#endregion
+export { toSafeValue };
+//# sourceMappingURL=safe-value.mjs.map

package/esm/safe-value.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-value.mjs","names":[],"sources":["../../../../../../devtools/src/safe-value.ts"],"sourcesContent":["const MAX_DEPTH = 6;\n\n/**\n * A JSON-safe snapshot of a value devtools keeps for later display.\n *\n * Log contexts and phase attributes are app data: they can hold live objects\n * (a request, its socket) whose graphs are circular and which must not be kept\n * alive by the collector anyway. Plain objects and arrays are copied; anything\n * with a `toJSON()` is serialized through it; other class instances collapse\n * to `[ClassName]`, cycles to `[Circular]`, and nesting past a fixed depth to\n * `[Object]` / `[Array]`.\n */\nexport function toSafeValue(value: unknown): unknown {\n  return snapshot(value, 0, new WeakSet());\n}\n\nfunction snapshot(value: unknown, depth: number, seen: WeakSet<object>): unknown {\n  if (value === null || value === undefined) return value;\n\n  switch (typeof value) {\n    case \"string\":\n    case \"number\":\n    case \"boolean\":\n      return value;\n    case \"bigint\":\n      return value.toString();\n    case \"symbol\":\n      return value.toString();\n    case \"function\":\n      return undefined;\n  }\n\n  const object = value as object;\n\n  if (seen.has(object)) return \"[Circular]\";\n  if (value instanceof Date) return Number.isNaN(value.getTime()) ? \"Invalid Date\" : value.toISOString();\n  if (value instanceof Error) return { name: value.name, message: value.message };\n\n  if (depth >= MAX_DEPTH) return Array.isArray(value) ? \"[Array]\" : \"[Object]\";\n\n  seen.add(object);\n\n  try {\n    if (Array.isArray(value)) return value.map((item) => snapshot(item, depth + 1, seen));\n\n    const prototype = Object.getPrototypeOf(object);\n\n    if (prototype !== Object.prototype && prototype !== null) {\n      const toJSON = (object as { toJSON?: unknown }).toJSON;\n\n      if (typeof toJSON === \"function\") {\n        try {\n          return snapshot(toJSON.call(object), depth + 1, seen);\n        } catch {\n          return `[${constructorName(object)}]`;\n        }\n      }\n\n      return `[${constructorName(object)}]`;\n    }\n\n    const copy: Record<string, unknown> = {};\n\n    for (const [key, entry] of Object.entries(object)) {\n      const safe = snapshot(entry, depth + 1, seen);\n      if (safe !== undefined) copy[key] = safe;\n    }\n\n    return copy;\n  } finally {\n    seen.delete(object);\n  }\n}\n\nfunction constructorName(object: object): string {\n  return (object as { constructor?: { name?: string } }).constructor?.name || \"Object\";\n}\n"],"mappings":";AAAA,MAAM,YAAY;;;;;;;;;;;AAYlB,SAAgB,YAAY,OAAyB;CACnD,OAAO,SAAS,OAAO,mBAAG,IAAI,QAAQ,CAAC;AACzC;AAEA,SAAS,SAAS,OAAgB,OAAe,MAAgC;CAC/E,IAAI,UAAU,QAAQ,UAAU,QAAW,OAAO;CAElD,QAAQ,OAAO,OAAf;EACE,KAAK;EACL,KAAK;EACL,KAAK,WACH,OAAO;EACT,KAAK,UACH,OAAO,MAAM,SAAS;EACxB,KAAK,UACH,OAAO,MAAM,SAAS;EACxB,KAAK,YACH;CACJ;CAEA,MAAM,SAAS;CAEf,IAAI,KAAK,IAAI,MAAM,GAAG,OAAO;CAC7B,IAAI,iBAAiB,MAAM,OAAO,OAAO,MAAM,MAAM,QAAQ,CAAC,IAAI,iBAAiB,MAAM,YAAY;CACrG,IAAI,iBAAiB,OAAO,OAAO;EAAE,MAAM,MAAM;EAAM,SAAS,MAAM;CAAQ;CAE9E,IAAI,SAAS,WAAW,OAAO,MAAM,QAAQ,KAAK,IAAI,YAAY;CAElE,KAAK,IAAI,MAAM;CAEf,IAAI;EACF,IAAI,MAAM,QAAQ,KAAK,GAAG,OAAO,MAAM,KAAK,SAAS,SAAS,MAAM,QAAQ,GAAG,IAAI,CAAC;EAEpF,MAAM,YAAY,OAAO,eAAe,MAAM;EAE9C,IAAI,cAAc,OAAO,aAAa,cAAc,MAAM;GACxD,MAAM,SAAU,OAAgC;GAEhD,IAAI,OAAO,WAAW,YACpB,IAAI;IACF,OAAO,SAAS,OAAO,KAAK,MAAM,GAAG,QAAQ,GAAG,IAAI;GACtD,QAAQ;IACN,OAAO,IAAI,gBAAgB,MAAM,EAAE;GACrC;GAGF,OAAO,IAAI,gBAAgB,MAAM,EAAE;EACrC;EAEA,MAAM,OAAgC,CAAC;EAEvC,KAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,MAAM,GAAG;GACjD,MAAM,OAAO,SAAS,OAAO,QAAQ,GAAG,IAAI;GAC5C,IAAI,SAAS,QAAW,KAAK,OAAO;EACtC;EAEA,OAAO;CACT,UAAU;EACR,KAAK,OAAO,MAAM;CACpB;AACF;AAEA,SAAS,gBAAgB,QAAwB;CAC/C,OAAQ,OAA+C,aAAa,QAAQ;AAC9E"}

package/esm/server/background-routes.mjs

@@ -0,0 +1,9 @@
+//#region ../devtools/src/server/background-routes.ts
+/** Registers the route that returns work recorded outside any request. */
+function registerBackgroundRoutes(server, deps) {
+	server.get("/api/background", async () => deps.collector.getBackground());
+}
+
+//#endregion
+export { registerBackgroundRoutes };
+//# sourceMappingURL=background-routes.mjs.map

package/esm/server/background-routes.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"background-routes.mjs","names":[],"sources":["../../../../../../../devtools/src/server/background-routes.ts"],"sourcesContent":["import type { FastifyInstance } from \"fastify\";\nimport type { MountDevtoolsRoutesDeps } from \"./types\";\n\n/** Registers the route that returns work recorded outside any request. */\nexport function registerBackgroundRoutes(\n  server: FastifyInstance,\n  deps: MountDevtoolsRoutesDeps,\n): void {\n  server.get(\"/api/background\", async () => deps.collector.getBackground());\n}\n"],"mappings":";;AAIA,SAAgB,yBACd,QACA,MACM;CACN,OAAO,IAAI,mBAAmB,YAAY,KAAK,UAAU,cAAc,CAAC;AAC1E"}

package/esm/server/explain-route.mjs

@@ -0,0 +1,37 @@
+//#region ../devtools/src/server/explain-route.ts
+/**
+* The value the logger's redaction substitutes for a censored leaf
+* (`logger/src/redact/redact.ts`, `DEFAULT_CENSOR`). Not exported from
+* `@warlock.js/logger`, so matched by literal here.
+*/
+const REDACTED_PLACEHOLDER = "[REDACTED]";
+function isExplainableSql(sql) {
+	return /^\s*(select|with)\b/i.test(sql ?? "");
+}
+/** Registers the EXPLAIN route: Postgres `SELECT`/`WITH` queries only. */
+function registerExplainRoute(server, deps) {
+	server.post("/api/requests/:requestId/queries/:queryId/explain", async (request, reply) => {
+		const query = deps.collector.getRequest(request.params.requestId)?.queries.find((item) => item.id === request.params.queryId);
+		if (!query) {
+			reply.code(404).send();
+			return;
+		}
+		if (query.driver !== "postgres" || !isExplainableSql(query.sql) || !deps.explain) {
+			reply.code(400).send({ error: "Only Postgres SELECT or WITH queries can be explained" });
+			return;
+		}
+		if (query.bindings?.some((binding) => binding === REDACTED_PLACEHOLDER)) {
+			reply.code(400).send({ error: "bindings redacted" });
+			return;
+		}
+		try {
+			return { plan: await deps.explain(query) };
+		} catch (error) {
+			reply.code(500).send({ error: error instanceof Error ? error.message : String(error) });
+		}
+	});
+}
+
+//#endregion
+export { registerExplainRoute };
+//# sourceMappingURL=explain-route.mjs.map