@warlock.js/devtools 5.26.0 → 5.28.0

package/esm/devtools-connector.mjs

@@ -52,12 +52,15 @@ function devtoolsConnector(options = {}) {
 			await attachSource(log, "mail", () => attachMailSource(collector));
 			await attachSource(log, "log", () => attachLogSource(collector));
 			const { mountDevtoolsRoutes } = await import("./server/index.mjs");
+			const postmanBuilder = await findPostmanBuilder();
 			mountDevtoolsRoutes(getHttpServer(), {
 				collector,
 				options: resolved,
 				isDevelopment: () => Application.runtimeStrategy === "development",
 				explain: (query) => explainQuery(query),
-				listRoutes: () => listRoutes()
+				listRoutes: () => listRoutes(),
+				getOpenApiDocument: () => getOpenApiDocument(),
+				getPostmanCollection: postmanBuilder ? async () => unwrapCollection(await postmanBuilder()) : void 0
 			});
 			disposers.push(collector.subscribe((event) => {
 				if (event.type !== "request" || event.data.warningCount === 0) return;
@@ -106,6 +109,38 @@ async function listRoutes() {
 		middleware: route.middleware?.map((middleware) => middleware.name || "anonymous")
 	}));
 }
+/**
+* Builds the OpenAPI 3.1 document from the routes registered in this process —
+* the same generator behind `warlock generate.openapi`. Core is imported
+* lazily so this module stays free of a load-time dependency on it.
+*/
+async function getOpenApiDocument() {
+	const { getDevelopmentOpenApiDocument } = await import("@warlock.js/core");
+	const { document } = await getDevelopmentOpenApiDocument();
+	return document;
+}
+/**
+* Looks up core's Postman collection builder, `getDevelopmentPostmanCollection`.
+* Older cores do not export it; the route then answers 503. The lookup is
+* guarded because a namespace without the export may throw on access. Core is
+* imported lazily, like the OpenAPI document above.
+*/
+async function findPostmanBuilder() {
+	try {
+		const build = (await import("@warlock.js/core")).getDevelopmentPostmanCollection;
+		return typeof build === "function" ? build : void 0;
+	} catch {
+		return;
+	}
+}
+/**
+* Core may return the collection itself or wrap it in `{ collection, warnings }`,
+* like the OpenAPI generator's `{ document, warnings }`.
+*/
+function unwrapCollection(result) {
+	if (result && typeof result === "object" && "collection" in result) return result.collection;
+	return result;
+}
 
 //#endregion
 export { devtoolsConnector };

package/esm/devtools-connector.mjs.map

@@ -1 +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"}
+{"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      const postmanBuilder = await findPostmanBuilder();\n\n      mountDevtoolsRoutes(getHttpServer(), {\n        collector,\n        options: resolved,\n        isDevelopment: () => Application.runtimeStrategy === \"development\",\n        explain: (query) => explainQuery(query),\n        listRoutes: () => listRoutes(),\n        getOpenApiDocument: () => getOpenApiDocument(),\n        getPostmanCollection: postmanBuilder\n          ? async () => unwrapCollection(await postmanBuilder())\n          : undefined,\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\n/**\n * Builds the OpenAPI 3.1 document from the routes registered in this process —\n * the same generator behind `warlock generate.openapi`. Core is imported\n * lazily so this module stays free of a load-time dependency on it.\n */\nasync function getOpenApiDocument(): Promise<object> {\n  const { getDevelopmentOpenApiDocument } = await import(\"@warlock.js/core\");\n  const { document } = await getDevelopmentOpenApiDocument();\n\n  return document;\n}\n\ntype PostmanBuilder = () => Promise<unknown>;\n\n/**\n * Looks up core's Postman collection builder, `getDevelopmentPostmanCollection`.\n * Older cores do not export it; the route then answers 503. The lookup is\n * guarded because a namespace without the export may throw on access. Core is\n * imported lazily, like the OpenAPI document above.\n */\nasync function findPostmanBuilder(): Promise<PostmanBuilder | undefined> {\n  try {\n    const core: Record<string, unknown> = await import(\"@warlock.js/core\");\n    const build = core.getDevelopmentPostmanCollection;\n\n    return typeof build === \"function\" ? (build as PostmanBuilder) : undefined;\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * Core may return the collection itself or wrap it in `{ collection, warnings }`,\n * like the OpenAPI generator's `{ document, warnings }`.\n */\nfunction unwrapCollection(result: unknown): object {\n  if (result && typeof result === \"object\" && \"collection\" in result) {\n    return (result as { collection: object }).collection;\n  }\n\n  return result as object;\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;GAC7C,MAAM,iBAAiB,MAAM,mBAAmB;GAEhD,oBAAoB,cAAc,GAAG;IACnC;IACA,SAAS;IACT,qBAAqB,YAAY,oBAAoB;IACrD,UAAU,UAAU,aAAa,KAAK;IACtC,kBAAkB,WAAW;IAC7B,0BAA0B,mBAAmB;IAC7C,sBAAsB,iBAClB,YAAY,iBAAiB,MAAM,eAAe,CAAC,IACnD;GACN,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;;;;;;AAOA,eAAe,qBAAsC;CACnD,MAAM,EAAE,kCAAkC,MAAM,OAAO;CACvD,MAAM,EAAE,aAAa,MAAM,8BAA8B;CAEzD,OAAO;AACT;;;;;;;AAUA,eAAe,qBAA0D;CACvE,IAAI;EAEF,MAAM,SAAQ,MAD8B,OAAO,oBACjC,CAAC;EAEnB,OAAO,OAAO,UAAU,aAAc,QAA2B;CACnE,QAAQ;EACN;CACF;AACF;;;;;AAMA,SAAS,iBAAiB,QAAyB;CACjD,IAAI,UAAU,OAAO,WAAW,YAAY,gBAAgB,QAC1D,OAAQ,OAAkC;CAG5C,OAAO;AACT"}

package/esm/server/index.mjs

@@ -3,10 +3,11 @@ import { registerExplainRoute } from "./explain-route.mjs";
 import { registerDevtoolsGuard } from "./guard.mjs";
 import { registerLogRoutes } from "./log-routes.mjs";
 import { registerMailRoutes } from "./mail-routes.mjs";
+import { registerUiAssets } from "./ui-assets.mjs";
+import { registerOpenApiRoutes } from "./openapi-routes.mjs";
 import { registerRequestsRoutes } from "./requests-routes.mjs";
 import { registerRouteRoutes } from "./route-routes.mjs";
 import { registerStreamRoute } from "./stream-route.mjs";
-import { registerUiAssets } from "./ui-assets.mjs";
 
 //#region ../devtools/src/server/index.ts
 /**
@@ -27,6 +28,7 @@ function mountDevtoolsRoutes(server, deps) {
 		registerMailRoutes(instance, deps);
 		registerLogRoutes(instance, deps);
 		registerRouteRoutes(instance, deps);
+		registerOpenApiRoutes(instance, deps);
 		registerExplainRoute(instance, deps);
 		registerStreamRoute(instance, deps);
 	}, { prefix: deps.options.path });

package/esm/server/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../../../../../../../devtools/src/server/index.ts"],"sourcesContent":["import type { FastifyError, FastifyInstance } from \"fastify\";\nimport { registerBackgroundRoutes } from \"./background-routes\";\nimport { registerExplainRoute } from \"./explain-route\";\nimport { registerDevtoolsGuard } from \"./guard\";\nimport { registerLogRoutes } from \"./log-routes\";\nimport { registerMailRoutes } from \"./mail-routes\";\nimport { registerRequestsRoutes } from \"./requests-routes\";\nimport { registerRouteRoutes } from \"./route-routes\";\nimport { registerStreamRoute } from \"./stream-route\";\nimport type { MountDevtoolsRoutesDeps } from \"./types\";\nimport { registerUiAssets } from \"./ui-assets\";\n\nexport type { DevtoolsRouteRow, MountDevtoolsRoutesDeps } from \"./types\";\n\n/**\n * Mounts the devtools dashboard and its API under `deps.options.path` on\n * `server`. Every route is registered inside a single encapsulated Fastify\n * context so the dev-only, loopback-only guard never reaches the app's\n * other routes.\n */\nexport function mountDevtoolsRoutes(server: FastifyInstance, deps: MountDevtoolsRoutesDeps): void {\n  server.register(\n    async (instance) => {\n      registerDevtoolsGuard(instance, deps);\n\n      instance.setErrorHandler((error: FastifyError, _request, reply) => {\n        reply.code(error.statusCode ?? 500).send({ error: error.message });\n      });\n\n      registerUiAssets(instance);\n      registerRequestsRoutes(instance, deps);\n      registerBackgroundRoutes(instance, deps);\n      registerMailRoutes(instance, deps);\n      registerLogRoutes(instance, deps);\n      registerRouteRoutes(instance, deps);\n      registerExplainRoute(instance, deps);\n      registerStreamRoute(instance, deps);\n    },\n    { prefix: deps.options.path },\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAoBA,SAAgB,oBAAoB,QAAyB,MAAqC;CAChG,OAAO,SACL,OAAO,aAAa;EAClB,sBAAsB,UAAU,IAAI;EAEpC,SAAS,iBAAiB,OAAqB,UAAU,UAAU;GACjE,MAAM,KAAK,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,EAAE,OAAO,MAAM,QAAQ,CAAC;EACnE,CAAC;EAED,iBAAiB,QAAQ;EACzB,uBAAuB,UAAU,IAAI;EACrC,yBAAyB,UAAU,IAAI;EACvC,mBAAmB,UAAU,IAAI;EACjC,kBAAkB,UAAU,IAAI;EAChC,oBAAoB,UAAU,IAAI;EAClC,qBAAqB,UAAU,IAAI;EACnC,oBAAoB,UAAU,IAAI;CACpC,GACA,EAAE,QAAQ,KAAK,QAAQ,KAAK,CAC9B;AACF"}
+{"version":3,"file":"index.mjs","names":[],"sources":["../../../../../../../devtools/src/server/index.ts"],"sourcesContent":["import type { FastifyError, FastifyInstance } from \"fastify\";\nimport { registerBackgroundRoutes } from \"./background-routes\";\nimport { registerExplainRoute } from \"./explain-route\";\nimport { registerDevtoolsGuard } from \"./guard\";\nimport { registerLogRoutes } from \"./log-routes\";\nimport { registerMailRoutes } from \"./mail-routes\";\nimport { registerOpenApiRoutes } from \"./openapi-routes\";\nimport { registerRequestsRoutes } from \"./requests-routes\";\nimport { registerRouteRoutes } from \"./route-routes\";\nimport { registerStreamRoute } from \"./stream-route\";\nimport type { MountDevtoolsRoutesDeps } from \"./types\";\nimport { registerUiAssets } from \"./ui-assets\";\n\nexport type { DevtoolsRouteRow, MountDevtoolsRoutesDeps } from \"./types\";\n\n/**\n * Mounts the devtools dashboard and its API under `deps.options.path` on\n * `server`. Every route is registered inside a single encapsulated Fastify\n * context so the dev-only, loopback-only guard never reaches the app's\n * other routes.\n */\nexport function mountDevtoolsRoutes(server: FastifyInstance, deps: MountDevtoolsRoutesDeps): void {\n  server.register(\n    async (instance) => {\n      registerDevtoolsGuard(instance, deps);\n\n      instance.setErrorHandler((error: FastifyError, _request, reply) => {\n        reply.code(error.statusCode ?? 500).send({ error: error.message });\n      });\n\n      registerUiAssets(instance);\n      registerRequestsRoutes(instance, deps);\n      registerBackgroundRoutes(instance, deps);\n      registerMailRoutes(instance, deps);\n      registerLogRoutes(instance, deps);\n      registerRouteRoutes(instance, deps);\n      registerOpenApiRoutes(instance, deps);\n      registerExplainRoute(instance, deps);\n      registerStreamRoute(instance, deps);\n    },\n    { prefix: deps.options.path },\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAqBA,SAAgB,oBAAoB,QAAyB,MAAqC;CAChG,OAAO,SACL,OAAO,aAAa;EAClB,sBAAsB,UAAU,IAAI;EAEpC,SAAS,iBAAiB,OAAqB,UAAU,UAAU;GACjE,MAAM,KAAK,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,EAAE,OAAO,MAAM,QAAQ,CAAC;EACnE,CAAC;EAED,iBAAiB,QAAQ;EACzB,uBAAuB,UAAU,IAAI;EACrC,yBAAyB,UAAU,IAAI;EACvC,mBAAmB,UAAU,IAAI;EACjC,kBAAkB,UAAU,IAAI;EAChC,oBAAoB,UAAU,IAAI;EAClC,sBAAsB,UAAU,IAAI;EACpC,qBAAqB,UAAU,IAAI;EACnC,oBAAoB,UAAU,IAAI;CACpC,GACA,EAAE,QAAQ,KAAK,QAAQ,KAAK,CAC9B;AACF"}

package/esm/server/openapi-routes.mjs

@@ -0,0 +1,36 @@
+import { resolveUiRoot } from "../ui-root.mjs";
+import { sendFile } from "./ui-assets.mjs";
+import path from "node:path";
+
+//#region ../devtools/src/server/openapi-routes.ts
+/**
+* Registers the API docs: `GET /api/openapi.json` returns the document core
+* builds from the registered routes (`deps.getOpenApiDocument`), and
+* `GET /docs` serves the page that renders it with Scalar and
+* `GET /docs/swagger` the same document in Swagger UI;
+* `GET /api/postman.json` returns the Postman collection core builds
+* (`deps.getPostmanCollection`). The pages use relative URLs, so it works under whatever base path the dashboard is
+* mounted on.
+*/
+function registerOpenApiRoutes(server, deps) {
+	server.get("/api/openapi.json", async (_request, reply) => {
+		if (!deps.getOpenApiDocument) return reply.code(503).header("Cache-Control", "no-store").send({ error: "The OpenAPI document is not available: the host did not provide a generator." });
+		reply.header("Cache-Control", "no-store");
+		return deps.getOpenApiDocument();
+	});
+	server.get("/api/postman.json", async (_request, reply) => {
+		if (!deps.getPostmanCollection) return reply.code(503).header("Cache-Control", "no-store").send({ error: "The Postman collection is not available: the host did not provide a generator." });
+		reply.header("Cache-Control", "no-store");
+		return deps.getPostmanCollection();
+	});
+	server.get("/docs", (_request, reply) => {
+		sendFile(reply, path.join(resolveUiRoot(), "docs.html"), "text/html; charset=utf-8");
+	});
+	server.get("/docs/swagger", (_request, reply) => {
+		sendFile(reply, path.join(resolveUiRoot(), "docs-swagger.html"), "text/html; charset=utf-8");
+	});
+}
+
+//#endregion
+export { registerOpenApiRoutes };
+//# sourceMappingURL=openapi-routes.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"openapi-routes.mjs","names":[],"sources":["../../../../../../../devtools/src/server/openapi-routes.ts"],"sourcesContent":["import path from \"node:path\";\nimport type { FastifyInstance } from \"fastify\";\nimport { resolveUiRoot } from \"../ui-root\";\nimport type { MountDevtoolsRoutesDeps } from \"./types\";\nimport { sendFile } from \"./ui-assets\";\n\n/**\n * Registers the API docs: `GET /api/openapi.json` returns the document core\n * builds from the registered routes (`deps.getOpenApiDocument`), and\n * `GET /docs` serves the page that renders it with Scalar and\n * `GET /docs/swagger` the same document in Swagger UI;\n * `GET /api/postman.json` returns the Postman collection core builds\n * (`deps.getPostmanCollection`). The pages use relative URLs, so it works under whatever base path the dashboard is\n * mounted on.\n */\nexport function registerOpenApiRoutes(\n  server: FastifyInstance,\n  deps: MountDevtoolsRoutesDeps,\n): void {\n  server.get(\"/api/openapi.json\", async (_request, reply) => {\n    if (!deps.getOpenApiDocument) {\n      return reply.code(503).header(\"Cache-Control\", \"no-store\").send({\n        error: \"The OpenAPI document is not available: the host did not provide a generator.\",\n      });\n    }\n\n    reply.header(\"Cache-Control\", \"no-store\");\n\n    return deps.getOpenApiDocument();\n  });\n\n  server.get(\"/api/postman.json\", async (_request, reply) => {\n    if (!deps.getPostmanCollection) {\n      return reply.code(503).header(\"Cache-Control\", \"no-store\").send({\n        error: \"The Postman collection is not available: the host did not provide a generator.\",\n      });\n    }\n\n    reply.header(\"Cache-Control\", \"no-store\");\n\n    return deps.getPostmanCollection();\n  });\n\n  server.get(\"/docs\", (_request, reply) => {\n    sendFile(reply, path.join(resolveUiRoot(), \"docs.html\"), \"text/html; charset=utf-8\");\n  });\n\n  server.get(\"/docs/swagger\", (_request, reply) => {\n    sendFile(reply, path.join(resolveUiRoot(), \"docs-swagger.html\"), \"text/html; charset=utf-8\");\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;AAeA,SAAgB,sBACd,QACA,MACM;CACN,OAAO,IAAI,qBAAqB,OAAO,UAAU,UAAU;EACzD,IAAI,CAAC,KAAK,oBACR,OAAO,MAAM,KAAK,GAAG,CAAC,CAAC,OAAO,iBAAiB,UAAU,CAAC,CAAC,KAAK,EAC9D,OAAO,+EACT,CAAC;EAGH,MAAM,OAAO,iBAAiB,UAAU;EAExC,OAAO,KAAK,mBAAmB;CACjC,CAAC;CAED,OAAO,IAAI,qBAAqB,OAAO,UAAU,UAAU;EACzD,IAAI,CAAC,KAAK,sBACR,OAAO,MAAM,KAAK,GAAG,CAAC,CAAC,OAAO,iBAAiB,UAAU,CAAC,CAAC,KAAK,EAC9D,OAAO,iFACT,CAAC;EAGH,MAAM,OAAO,iBAAiB,UAAU;EAExC,OAAO,KAAK,qBAAqB;CACnC,CAAC;CAED,OAAO,IAAI,UAAU,UAAU,UAAU;EACvC,SAAS,OAAO,KAAK,KAAK,cAAc,GAAG,WAAW,GAAG,0BAA0B;CACrF,CAAC;CAED,OAAO,IAAI,kBAAkB,UAAU,UAAU;EAC/C,SAAS,OAAO,KAAK,KAAK,cAAc,GAAG,mBAAmB,GAAG,0BAA0B;CAC7F,CAAC;AACH"}

package/esm/server/ui-assets.mjs

@@ -1,38 +1,64 @@
 import { resolveUiRoot } from "../ui-root.mjs";
-import { readFileSync } from "node:fs";
 import path from "node:path";
+import { readFileSync } from "node:fs";
 
 //#region ../devtools/src/server/ui-assets.ts
-const ASSET_CONTENT_TYPES = {
-	"app.js": "text/javascript; charset=utf-8",
-	"app.css": "text/css; charset=utf-8"
+const uiFile = (name) => () => path.join(resolveUiRoot(), name);
+/**
+* The only assets that can be requested. The request's asset name is looked
+* up here and never joined into a filesystem path.
+*/
+const UI_ASSETS = {
+	"app.js": {
+		contentType: "text/javascript; charset=utf-8",
+		file: uiFile("app.js")
+	},
+	"app.css": {
+		contentType: "text/css; charset=utf-8",
+		file: uiFile("app.css")
+	},
+	"scalar.js": {
+		contentType: "text/javascript; charset=utf-8",
+		file: uiFile("vendor/scalar/standalone.js")
+	},
+	"swagger-ui-bundle.js": {
+		contentType: "text/javascript; charset=utf-8",
+		file: uiFile("vendor/swagger-ui/swagger-ui-bundle.js")
+	},
+	"swagger-ui.css": {
+		contentType: "text/css; charset=utf-8",
+		file: uiFile("vendor/swagger-ui/swagger-ui.css")
+	},
+	"docs-swagger.js": {
+		contentType: "text/javascript; charset=utf-8",
+		file: uiFile("docs-swagger.js")
+	}
 };
+/** Sends `file` with `contentType` and no caching. */
 function sendFile(reply, file, contentType) {
 	reply.header("Cache-Control", "no-store").header("Content-Type", contentType).send(readFileSync(file));
 }
 /**
 * Serves the static dashboard: `index.html` at the dashboard root and the
-* two named assets. The asset name is matched against a fixed whitelist —
-* never joined into a filesystem path — so no request can traverse outside
-* `ui/`.
+* whitelisted assets (`app.js`, `app.css`, the vendored Scalar bundle as
+* `scalar.js`, and the vendored Swagger UI files plus their init script). The asset name is matched against a fixed whitelist — never
+* joined into a filesystem path — so no request can traverse outside it.
 */
 function registerUiAssets(server) {
 	const serveIndex = (_request, reply) => {
-		const uiRoot = resolveUiRoot();
-		sendFile(reply, path.join(uiRoot, "index.html"), "text/html; charset=utf-8");
+		sendFile(reply, path.join(resolveUiRoot(), "index.html"), "text/html; charset=utf-8");
 	};
 	server.get("/", serveIndex);
 	server.get("/assets/:name", (request, reply) => {
-		const contentType = ASSET_CONTENT_TYPES[request.params.name];
-		if (!contentType) {
+		const asset = Object.hasOwn(UI_ASSETS, request.params.name) ? UI_ASSETS[request.params.name] : void 0;
+		if (!asset) {
 			reply.code(404).header("Cache-Control", "no-store").send();
 			return;
 		}
-		const uiRoot = resolveUiRoot();
-		sendFile(reply, path.join(uiRoot, request.params.name), contentType);
+		sendFile(reply, asset.file(), asset.contentType);
 	});
 }
 
 //#endregion
-export { registerUiAssets };
+export { registerUiAssets, sendFile };
 //# sourceMappingURL=ui-assets.mjs.map

package/esm/server/ui-assets.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"ui-assets.mjs","names":[],"sources":["../../../../../../../devtools/src/server/ui-assets.ts"],"sourcesContent":["import { readFileSync } from \"node:fs\";\nimport path from \"node:path\";\nimport type { FastifyInstance, FastifyReply } from \"fastify\";\nimport { resolveUiRoot } from \"../ui-root\";\n\nconst ASSET_CONTENT_TYPES: Record<string, string> = {\n  \"app.js\": \"text/javascript; charset=utf-8\",\n  \"app.css\": \"text/css; charset=utf-8\",\n};\n\nfunction sendFile(reply: FastifyReply, file: string, contentType: string): void {\n  reply\n    .header(\"Cache-Control\", \"no-store\")\n    .header(\"Content-Type\", contentType)\n    .send(readFileSync(file));\n}\n\n/**\n * Serves the static dashboard: `index.html` at the dashboard root and the\n * two named assets. The asset name is matched against a fixed whitelist —\n * never joined into a filesystem path — so no request can traverse outside\n * `ui/`.\n */\nexport function registerUiAssets(server: FastifyInstance): void {\n  const serveIndex = (_request: unknown, reply: FastifyReply): void => {\n    const uiRoot = resolveUiRoot();\n    sendFile(reply, path.join(uiRoot, \"index.html\"), \"text/html; charset=utf-8\");\n  };\n\n  server.get(\"/\", serveIndex);\n\n  server.get<{ Params: { name: string } }>(\"/assets/:name\", (request, reply) => {\n    const contentType = ASSET_CONTENT_TYPES[request.params.name];\n\n    if (!contentType) {\n      reply.code(404).header(\"Cache-Control\", \"no-store\").send();\n      return;\n    }\n\n    const uiRoot = resolveUiRoot();\n    sendFile(reply, path.join(uiRoot, request.params.name), contentType);\n  });\n}\n"],"mappings":";;;;;AAKA,MAAM,sBAA8C;CAClD,UAAU;CACV,WAAW;AACb;AAEA,SAAS,SAAS,OAAqB,MAAc,aAA2B;CAC9E,MACG,OAAO,iBAAiB,UAAU,CAAC,CACnC,OAAO,gBAAgB,WAAW,CAAC,CACnC,KAAK,aAAa,IAAI,CAAC;AAC5B;;;;;;;AAQA,SAAgB,iBAAiB,QAA+B;CAC9D,MAAM,cAAc,UAAmB,UAA8B;EACnE,MAAM,SAAS,cAAc;EAC7B,SAAS,OAAO,KAAK,KAAK,QAAQ,YAAY,GAAG,0BAA0B;CAC7E;CAEA,OAAO,IAAI,KAAK,UAAU;CAE1B,OAAO,IAAkC,kBAAkB,SAAS,UAAU;EAC5E,MAAM,cAAc,oBAAoB,QAAQ,OAAO;EAEvD,IAAI,CAAC,aAAa;GAChB,MAAM,KAAK,GAAG,CAAC,CAAC,OAAO,iBAAiB,UAAU,CAAC,CAAC,KAAK;GACzD;EACF;EAEA,MAAM,SAAS,cAAc;EAC7B,SAAS,OAAO,KAAK,KAAK,QAAQ,QAAQ,OAAO,IAAI,GAAG,WAAW;CACrE,CAAC;AACH"}
+{"version":3,"file":"ui-assets.mjs","names":[],"sources":["../../../../../../../devtools/src/server/ui-assets.ts"],"sourcesContent":["import { readFileSync } from \"node:fs\";\nimport path from \"node:path\";\nimport type { FastifyInstance, FastifyReply } from \"fastify\";\nimport { resolveUiRoot } from \"../ui-root\";\n\n/**\n * Where an asset's bytes come from: a file in this package's `ui/` folder.\n */\ntype UiAsset = {\n  contentType: string;\n  file: () => string;\n};\n\nconst uiFile = (name: string) => () => path.join(resolveUiRoot(), name);\n\n/**\n * The only assets that can be requested. The request's asset name is looked\n * up here and never joined into a filesystem path.\n */\nconst UI_ASSETS: Record<string, UiAsset> = {\n  \"app.js\": { contentType: \"text/javascript; charset=utf-8\", file: uiFile(\"app.js\") },\n  \"app.css\": { contentType: \"text/css; charset=utf-8\", file: uiFile(\"app.css\") },\n  \"scalar.js\": {\n    contentType: \"text/javascript; charset=utf-8\",\n    file: uiFile(\"vendor/scalar/standalone.js\"),\n  },\n  \"swagger-ui-bundle.js\": {\n    contentType: \"text/javascript; charset=utf-8\",\n    file: uiFile(\"vendor/swagger-ui/swagger-ui-bundle.js\"),\n  },\n  \"swagger-ui.css\": {\n    contentType: \"text/css; charset=utf-8\",\n    file: uiFile(\"vendor/swagger-ui/swagger-ui.css\"),\n  },\n  \"docs-swagger.js\": {\n    contentType: \"text/javascript; charset=utf-8\",\n    file: uiFile(\"docs-swagger.js\"),\n  },\n};\n\n/** Sends `file` with `contentType` and no caching. */\nexport function sendFile(reply: FastifyReply, file: string, contentType: string): void {\n  reply\n    .header(\"Cache-Control\", \"no-store\")\n    .header(\"Content-Type\", contentType)\n    .send(readFileSync(file));\n}\n\n/**\n * Serves the static dashboard: `index.html` at the dashboard root and the\n * whitelisted assets (`app.js`, `app.css`, the vendored Scalar bundle as\n * `scalar.js`, and the vendored Swagger UI files plus their init script). The asset name is matched against a fixed whitelist — never\n * joined into a filesystem path — so no request can traverse outside it.\n */\nexport function registerUiAssets(server: FastifyInstance): void {\n  const serveIndex = (_request: unknown, reply: FastifyReply): void => {\n    sendFile(reply, path.join(resolveUiRoot(), \"index.html\"), \"text/html; charset=utf-8\");\n  };\n\n  server.get(\"/\", serveIndex);\n\n  server.get<{ Params: { name: string } }>(\"/assets/:name\", (request, reply) => {\n    const asset = Object.hasOwn(UI_ASSETS, request.params.name)\n      ? UI_ASSETS[request.params.name]\n      : undefined;\n\n    if (!asset) {\n      reply.code(404).header(\"Cache-Control\", \"no-store\").send();\n      return;\n    }\n\n    sendFile(reply, asset.file(), asset.contentType);\n  });\n}\n"],"mappings":";;;;;AAaA,MAAM,UAAU,eAAuB,KAAK,KAAK,cAAc,GAAG,IAAI;;;;;AAMtE,MAAM,YAAqC;CACzC,UAAU;EAAE,aAAa;EAAkC,MAAM,OAAO,QAAQ;CAAE;CAClF,WAAW;EAAE,aAAa;EAA2B,MAAM,OAAO,SAAS;CAAE;CAC7E,aAAa;EACX,aAAa;EACb,MAAM,OAAO,6BAA6B;CAC5C;CACA,wBAAwB;EACtB,aAAa;EACb,MAAM,OAAO,wCAAwC;CACvD;CACA,kBAAkB;EAChB,aAAa;EACb,MAAM,OAAO,kCAAkC;CACjD;CACA,mBAAmB;EACjB,aAAa;EACb,MAAM,OAAO,iBAAiB;CAChC;AACF;;AAGA,SAAgB,SAAS,OAAqB,MAAc,aAA2B;CACrF,MACG,OAAO,iBAAiB,UAAU,CAAC,CACnC,OAAO,gBAAgB,WAAW,CAAC,CACnC,KAAK,aAAa,IAAI,CAAC;AAC5B;;;;;;;AAQA,SAAgB,iBAAiB,QAA+B;CAC9D,MAAM,cAAc,UAAmB,UAA8B;EACnE,SAAS,OAAO,KAAK,KAAK,cAAc,GAAG,YAAY,GAAG,0BAA0B;CACtF;CAEA,OAAO,IAAI,KAAK,UAAU;CAE1B,OAAO,IAAkC,kBAAkB,SAAS,UAAU;EAC5E,MAAM,QAAQ,OAAO,OAAO,WAAW,QAAQ,OAAO,IAAI,IACtD,UAAU,QAAQ,OAAO,QACzB;EAEJ,IAAI,CAAC,OAAO;GACV,MAAM,KAAK,GAAG,CAAC,CAAC,OAAO,iBAAiB,UAAU,CAAC,CAAC,KAAK;GACzD;EACF;EAEA,SAAS,OAAO,MAAM,KAAK,GAAG,MAAM,WAAW;CACjD,CAAC;AACH"}

package/esm/ui-root.mjs

@@ -1,6 +1,6 @@
 import { fileURLToPath } from "node:url";
-import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
+import { existsSync, readFileSync } from "node:fs";
 
 //#region ../devtools/src/ui-root.ts
 let cachedUiRoot;

package/llms-full.txt

@@ -8,7 +8,7 @@
 
 ---
 name: devtools-overview
-description: 'Development-only dashboard for Warlock.js apps at `/__warlock`: request timeline (router + page middleware, loaders, render, deferred values), every SQL/Mongo query with EXPLAIN, N+1 warnings naming the file and line, a dev mailbox, logs, cache operations and the route map. Use for: "why is this page slow", "which queries does this request run", "find N+1 queries", "see the email my app just sent in dev", "open the dashboard". Install with `warlock add devtools`; never registered in warlock.config.ts. Not this package: production monitoring/APM or OpenTelemetry export — use `http.tracing` hooks in @warlock.js/core; slow-query logging in production — subscribe to cascade `dataSourceRegistry.on("query")` yourself.'
+description: 'Development-only dashboard for Warlock.js apps at `/__warlock`: request timeline (router + page middleware, loaders, render, deferred values), every SQL/Mongo query with EXPLAIN, N+1 warnings naming the file and line, a dev mailbox, logs, cache operations, the route map and an API docs page (`/__warlock/docs`, the OpenAPI 3.1 document of the app rendered with Scalar or Swagger UI at `/__warlock/docs/swagger`, with OpenAPI and Postman downloads). Use for: "why is this page slow", "which queries does this request run", "find N+1 queries", "see the email my app just sent in dev", "open the dashboard", "browse my API docs in dev", "see the OpenAPI for my routes", "open Swagger UI for my API", "export my routes to Postman". Install with `warlock add devtools`; never registered in warlock.config.ts. Not this package: production monitoring/APM or OpenTelemetry export — use `http.tracing` hooks in @warlock.js/core; slow-query logging in production — subscribe to cascade `dataSourceRegistry.on("query")` yourself.'
 ---
 
 # `@warlock.js/devtools` — overview
@@ -53,10 +53,22 @@ of it would fail to resolve there.
 | **Logs** | Log entries per request, filterable by level and module | a logger channel |
 | **Cache** | hit / miss / set / removed / `invalidated` (tags, keys removed) | cache `cache.on(...)` |
 | **Routes** | Every HTTP route with its method, path, name and middleware | core router |
+| **API** | The app's API reference: every route with its parameters, request body, responses and auth | core `getDevelopmentOpenApiDocument()` |
 
 Work outside a request (boot, scheduler ticks, queue jobs) goes to a separate
 background list, so it never clutters a request's timeline.
 
+## API docs
+
+`/__warlock/docs` renders the app's OpenAPI 3.1 document with [Scalar](https://github.com/scalar/scalar); the dashboard's **API** tab shows the same page and has a **Scalar | Swagger UI** switch (remembered in the browser). `/__warlock/docs/swagger` renders the same document with [Swagger UI](https://github.com/swagger-api/swagger-ui). The document comes from `GET /__warlock/api/openapi.json`, built in-process by core's `getDevelopmentOpenApiDocument()` from the routes already registered, so it is the same generator as `warlock generate.openapi` and follows your edits with no CLI run. It covers API routes (not pages): paths, parameters, request bodies from Seal validation, responses from each handler's `responseSchema`, `401`/`422` and bearer/cookie security from `authMiddleware()`. See core's `generate-openapi` topic for what is documented and how to declare it.
+
+- It answers `503` from `/__warlock/api/openapi.json` when the host provides no generator.
+- Same guard as the rest of devtools: dev-only and loopback-only.
+- Scalar's prebuilt bundle is vendored and served as `assets/scalar.js`, so apps install nothing extra. The page fetches nothing from a CDN, and Scalar's web fonts, telemetry, AI agent and MCP are turned off.
+- Swagger UI's prebuilt bundle (swagger-ui-dist, Apache-2.0) is vendored too, served as `assets/swagger-ui-bundle.js` and `assets/swagger-ui.css`; its schema validator badge is off, so it fetches nothing from outside either.
+- The API tab links `OpenAPI JSON` (`/__warlock/api/openapi.json`) and `Postman collection` (`/__warlock/api/postman.json`, built by core's `getDevelopmentPostmanCollection()`; `503` when core cannot build one) for importing the routes into Postman or Insomnia.
+- To write a file instead, run `warlock generate.openapi` (default `storage/openapi/openapi.json`).
+
 ## Options
 
 `warlock dev` uses the defaults: path `/__warlock`, the last 200 requests

package/llms.txt

@@ -6,4 +6,4 @@
 
 ## Skills
 
-- [devtools-overview](@warlock.js/devtools/devtools-overview/SKILL.md): Development-only dashboard for Warlock.js apps at `/__warlock`: request timeline (router + page middleware, loaders, render, deferred values), every SQL/Mongo query with EXPLAIN, N+1 warnings naming the file and line, a dev mailbox, logs, cache operations and the route map. Use for: "why is this page slow", "which queries does this request run", "find N+1 queries", "see the email my app just sent in dev", "open the dashboard". Install with `warlock add devtools`; never registered in warlock.config.ts. Not this package: production monitoring/APM or OpenTelemetry export — use `http.tracing` hooks in @warlock.js/core; slow-query logging in production — subscribe to cascade `dataSourceRegistry.on("query")` yourself.
+- [devtools-overview](@warlock.js/devtools/devtools-overview/SKILL.md): Development-only dashboard for Warlock.js apps at `/__warlock`: request timeline (router + page middleware, loaders, render, deferred values), every SQL/Mongo query with EXPLAIN, N+1 warnings naming the file and line, a dev mailbox, logs, cache operations, the route map and an API docs page (`/__warlock/docs`, the OpenAPI 3.1 document of the app rendered with Scalar or Swagger UI at `/__warlock/docs/swagger`, with OpenAPI and Postman downloads). Use for: "why is this page slow", "which queries does this request run", "find N+1 queries", "see the email my app just sent in dev", "open the dashboard", "browse my API docs in dev", "see the OpenAPI for my routes", "open Swagger UI for my API", "export my routes to Postman". Install with `warlock add devtools`; never registered in warlock.config.ts. Not this package: production monitoring/APM or OpenTelemetry export — use `http.tracing` hooks in @warlock.js/core; slow-query logging in production — subscribe to cascade `dataSourceRegistry.on("query")` yourself.

package/package.json

@@ -5,10 +5,10 @@
     "environment": "server"
   },
   "peerDependencies": {
-    "@warlock.js/cache": "5.26.0",
-    "@warlock.js/cascade": "5.26.0",
-    "@warlock.js/core": "5.26.0",
-    "@warlock.js/logger": "5.26.0"
+    "@warlock.js/cache": "5.28.0",
+    "@warlock.js/cascade": "5.28.0",
+    "@warlock.js/core": "5.28.0",
+    "@warlock.js/logger": "5.28.0"
   },
   "peerDependenciesMeta": {
     "@warlock.js/cache": {
@@ -33,7 +33,7 @@
   ],
   "author": "hassanzohdy",
   "license": "MIT",
-  "version": "5.26.0",
+  "version": "5.28.0",
   "main": "./cjs/index.cjs",
   "module": "./esm/index.mjs",
   "types": "./esm/index.d.mts",

package/skills/devtools-overview/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: devtools-overview
-description: 'Development-only dashboard for Warlock.js apps at `/__warlock`: request timeline (router + page middleware, loaders, render, deferred values), every SQL/Mongo query with EXPLAIN, N+1 warnings naming the file and line, a dev mailbox, logs, cache operations and the route map. Use for: "why is this page slow", "which queries does this request run", "find N+1 queries", "see the email my app just sent in dev", "open the dashboard". Install with `warlock add devtools`; never registered in warlock.config.ts. Not this package: production monitoring/APM or OpenTelemetry export — use `http.tracing` hooks in @warlock.js/core; slow-query logging in production — subscribe to cascade `dataSourceRegistry.on("query")` yourself.'
+description: 'Development-only dashboard for Warlock.js apps at `/__warlock`: request timeline (router + page middleware, loaders, render, deferred values), every SQL/Mongo query with EXPLAIN, N+1 warnings naming the file and line, a dev mailbox, logs, cache operations, the route map and an API docs page (`/__warlock/docs`, the OpenAPI 3.1 document of the app rendered with Scalar or Swagger UI at `/__warlock/docs/swagger`, with OpenAPI and Postman downloads). Use for: "why is this page slow", "which queries does this request run", "find N+1 queries", "see the email my app just sent in dev", "open the dashboard", "browse my API docs in dev", "see the OpenAPI for my routes", "open Swagger UI for my API", "export my routes to Postman". Install with `warlock add devtools`; never registered in warlock.config.ts. Not this package: production monitoring/APM or OpenTelemetry export — use `http.tracing` hooks in @warlock.js/core; slow-query logging in production — subscribe to cascade `dataSourceRegistry.on("query")` yourself.'
 ---
 
 # `@warlock.js/devtools` — overview
@@ -45,10 +45,22 @@ of it would fail to resolve there.
 | **Logs** | Log entries per request, filterable by level and module | a logger channel |
 | **Cache** | hit / miss / set / removed / `invalidated` (tags, keys removed) | cache `cache.on(...)` |
 | **Routes** | Every HTTP route with its method, path, name and middleware | core router |
+| **API** | The app's API reference: every route with its parameters, request body, responses and auth | core `getDevelopmentOpenApiDocument()` |
 
 Work outside a request (boot, scheduler ticks, queue jobs) goes to a separate
 background list, so it never clutters a request's timeline.
 
+## API docs
+
+`/__warlock/docs` renders the app's OpenAPI 3.1 document with [Scalar](https://github.com/scalar/scalar); the dashboard's **API** tab shows the same page and has a **Scalar | Swagger UI** switch (remembered in the browser). `/__warlock/docs/swagger` renders the same document with [Swagger UI](https://github.com/swagger-api/swagger-ui). The document comes from `GET /__warlock/api/openapi.json`, built in-process by core's `getDevelopmentOpenApiDocument()` from the routes already registered, so it is the same generator as `warlock generate.openapi` and follows your edits with no CLI run. It covers API routes (not pages): paths, parameters, request bodies from Seal validation, responses from each handler's `responseSchema`, `401`/`422` and bearer/cookie security from `authMiddleware()`. See core's `generate-openapi` topic for what is documented and how to declare it.
+
+- It answers `503` from `/__warlock/api/openapi.json` when the host provides no generator.
+- Same guard as the rest of devtools: dev-only and loopback-only.
+- Scalar's prebuilt bundle is vendored and served as `assets/scalar.js`, so apps install nothing extra. The page fetches nothing from a CDN, and Scalar's web fonts, telemetry, AI agent and MCP are turned off.
+- Swagger UI's prebuilt bundle (swagger-ui-dist, Apache-2.0) is vendored too, served as `assets/swagger-ui-bundle.js` and `assets/swagger-ui.css`; its schema validator badge is off, so it fetches nothing from outside either.
+- The API tab links `OpenAPI JSON` (`/__warlock/api/openapi.json`) and `Postman collection` (`/__warlock/api/postman.json`, built by core's `getDevelopmentPostmanCollection()`; `503` when core cannot build one) for importing the routes into Postman or Insomnia.
+- To write a file instead, run `warlock generate.openapi` (default `storage/openapi/openapi.json`).
+
 ## Options
 
 `warlock dev` uses the defaults: path `/__warlock`, the last 200 requests

package/ui/app.css

@@ -330,6 +330,20 @@ details summary {
 .log-success {
   color: var(--good);
 }
+.toolbar-link {
+  margin-left: 6px;
+}
+.toolbar-link:first-of-type {
+  margin-left: auto;
+}
+.docs-frame {
+  display: block;
+  width: 100%;
+  height: calc(100vh - 165px);
+  border: 1px solid var(--line);
+  border-radius: 7px;
+  background: var(--surface);
+}
 @media (max-width: 700px) {
   .topbar {
     gap: 10px;

package/ui/app.js

@@ -467,6 +467,74 @@ async function routesView() {
   return section;
 }
 
+const DOCS_VIEWERS = [
+  { id: "scalar", label: "Scalar", src: "docs" },
+  { id: "swagger", label: "Swagger UI", src: "docs/swagger" },
+];
+const DOCS_VIEWER_KEY = "warlock-devtools-docs-viewer";
+
+function savedDocsViewer() {
+  try {
+    const id = localStorage.getItem(DOCS_VIEWER_KEY);
+    return DOCS_VIEWERS.find((viewer) => viewer.id === id) || DOCS_VIEWERS[0];
+  } catch {
+    return DOCS_VIEWERS[0];
+  }
+}
+
+function saveDocsViewer(viewer) {
+  try {
+    localStorage.setItem(DOCS_VIEWER_KEY, viewer.id);
+  } catch {
+    // Storage can be blocked; the choice then lasts until the tab changes.
+  }
+}
+
+function apiView() {
+  const section = el("section");
+  const frame = el("iframe", { class: "docs-frame", title: "API reference" });
+  const buttons = DOCS_VIEWERS.map((viewer) =>
+    el("button", {
+      class: "toggle",
+      type: "button",
+      text: viewer.label,
+    }),
+  );
+  const show = (viewer) => {
+    frame.src = viewer.src;
+    buttons.forEach((button, index) =>
+      button.classList.toggle("is-active", DOCS_VIEWERS[index] === viewer),
+    );
+  };
+  const pick = (viewer) => {
+    saveDocsViewer(viewer);
+    show(viewer);
+  };
+  buttons.forEach((button, index) =>
+    button.addEventListener("click", () => pick(DOCS_VIEWERS[index])),
+  );
+  section.append(
+    el("div", { class: "toolbar" }, [
+      ...buttons,
+      el("a", {
+        class: "toolbar-link",
+        href: "api/openapi.json",
+        download: "openapi.json",
+        text: "OpenAPI JSON",
+      }),
+      el("a", {
+        class: "toolbar-link",
+        href: "api/postman.json",
+        download: "postman.json",
+        text: "Postman collection",
+      }),
+    ]),
+    frame,
+  );
+  show(savedDocsViewer());
+  return section;
+}
+
 async function render() {
   try {
     const view =
@@ -478,7 +546,9 @@ async function render() {
             ? await mailView()
             : state.tab === "logs"
               ? await logsView()
-              : await routesView();
+              : state.tab === "routes"
+                ? await routesView()
+                : apiView();
     app.replaceChildren(view);
   } catch (error) {
     app.replaceChildren(errorView(error));

package/ui/docs-swagger.html

@@ -0,0 +1,15 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>API reference (Swagger UI)</title>
+    <!-- Every URL is relative to /docs/swagger, so the page works under any dashboard base path. -->
+    <link rel="stylesheet" href="../assets/swagger-ui.css" />
+  </head>
+  <body>
+    <div id="swagger-ui"></div>
+    <script src="../assets/swagger-ui-bundle.js"></script>
+    <script src="../assets/docs-swagger.js"></script>
+  </body>
+</html>

package/ui/docs-swagger.js

@@ -0,0 +1,10 @@
+// Starts Swagger UI on the page. The document URL is relative to /docs/swagger,
+// so it works under any dashboard base path. The validator badge is off
+// (`validatorUrl: null`): this is a loopback dev tool and must not call out.
+window.ui = SwaggerUIBundle({
+  url: "../api/openapi.json",
+  dom_id: "#swagger-ui",
+  validatorUrl: null,
+  deepLinking: true,
+  persistAuthorization: false,
+});

package/ui/docs.html

@@ -0,0 +1,17 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>API reference</title>
+  </head>
+  <body>
+    <!-- Scalar reads its settings from this element. Every URL is relative to /docs, so the page works under any dashboard base path. Fonts, telemetry, the AI agent and MCP are off: this is a loopback dev tool and must not call out. -->
+    <script
+      id="api-reference"
+      data-url="api/openapi.json"
+      data-configuration='{"withDefaultFonts":false,"telemetry":false,"showDeveloperTools":"never","agent":{"disabled":true},"mcp":{"disabled":true}}'
+    ></script>
+    <script src="assets/scalar.js"></script>
+  </body>
+</html>

package/ui/index.html

@@ -15,6 +15,7 @@
         <button class="tab" data-tab="mail">Mail</button>
         <button class="tab" data-tab="logs">Logs</button>
         <button class="tab" data-tab="routes">Routes</button>
+        <button class="tab" data-tab="api">API</button>
       </nav>
       <button id="clear" class="clear" type="button">Clear</button>
     </header>

package/ui/vendor/scalar/LICENSE.md

@@ -0,0 +1,34 @@
+# Scalar API Reference (vendored)
+
+`standalone.js` is the unmodified prebuilt browser bundle of
+[`@scalar/api-reference`](https://github.com/scalar/scalar) **1.72.2**
+(`dist/browser/standalone.js` in the npm package), vendored so apps that add
+`@warlock.js/devtools` install nothing extra. It is served only by the
+devtools API docs page (`/__warlock/docs`), in development, to loopback clients.
+
+To update: `npm pack @scalar/api-reference@<version>`, extract
+`package/dist/browser/standalone.js` over this file, and update the version above.
+
+## License
+
+MIT License
+
+Copyright (c) Scalar (https://github.com/scalar)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.