@warlock.js/devtools 5.25.0 → 5.27.0

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,26 @@
+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. The page uses
+* 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("/docs", (_request, reply) => {
+		sendFile(reply, path.join(resolveUiRoot(), "docs.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. The page uses\n * 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(\"/docs\", (_request, reply) => {\n    sendFile(reply, path.join(resolveUiRoot(), \"docs.html\"), \"text/html; charset=utf-8\");\n  });\n}\n"],"mappings":";;;;;;;;;;;;AAaA,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,UAAU,UAAU,UAAU;EACvC,SAAS,OAAO,KAAK,KAAK,cAAc,GAAG,WAAW,GAAG,0BAA0B;CACrF,CAAC;AACH"}

package/esm/server/ui-assets.mjs

@@ -1,38 +1,52 @@
 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")
+	}
 };
+/** 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`, and the vendored Scalar bundle
+* as `scalar.js`). 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};\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`, and the vendored Scalar bundle\n * as `scalar.js`). 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;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). 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". 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,20 @@ 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. 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.
+- To keep a file for Postman or Insomnia, run `warlock generate.openapi` (default `storage/openapi/openapi.json`) instead.
+
 ## 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). 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". 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.25.0",
-    "@warlock.js/cascade": "5.25.0",
-    "@warlock.js/core": "5.25.0",
-    "@warlock.js/logger": "5.25.0"
+    "@warlock.js/cache": "5.27.0",
+    "@warlock.js/cascade": "5.27.0",
+    "@warlock.js/core": "5.27.0",
+    "@warlock.js/logger": "5.27.0"
   },
   "peerDependenciesMeta": {
     "@warlock.js/cache": {
@@ -33,7 +33,7 @@
   ],
   "author": "hassanzohdy",
   "license": "MIT",
-  "version": "5.25.0",
+  "version": "5.27.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). 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". 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,20 @@ 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. 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.
+- To keep a file for Postman or Insomnia, run `warlock generate.openapi` (default `storage/openapi/openapi.json`) instead.
+
 ## Options
 
 `warlock dev` uses the defaults: path `/__warlock`, the last 200 requests

package/ui/app.css

@@ -330,6 +330,14 @@ details summary {
 .log-success {
   color: var(--good);
 }
+.docs-frame {
+  display: block;
+  width: 100%;
+  height: calc(100vh - 110px);
+  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,10 @@ async function routesView() {
   return section;
 }
 
+function apiView() {
+  return el("iframe", { class: "docs-frame", src: "docs", title: "API reference" });
+}
+
 async function render() {
   try {
     const view =
@@ -478,7 +482,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.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.